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This publication provides information on the Special Beal Time Operating 
System (5799- AHE) . 

This manual is organized so that it can be used as four separate 
manuals, each chapter addressing the needs of a different audience- 
In each case, the intended audience is a group within a typical computer 
department. The intended audience and the applicable chapters are: 



• Management — Chapter 1 - GENERAL INFORMATION 

• Application Programmers — Chapter 2 - APPLICATION SERVICES 

• System Programmers — Chapter 3 - INSTALLATION GUIDE 

• Operators — Chapter H - OPERATORS' REFERENCE 

The intended audience for the section entitled "GENERAL INFORMATION" 
includes those people wishing to gain an overview of the Special Real 
Time Operating System and to become familiar with the general functions 
of the PRPQ, This chapter is prerequisite reading to the following 
chapters. 

The section entitled "APPLICATION SERVICES" is intended to be used by 
programmers to gain knowledge of the realtime system concepts and 
processing methods. It is technically oriented. Users of this section 
should have a thorough knowledge of programming techniques as well as 
a general knowledge of Operating System/Virtual Storage (OS/VSI). The 
parts of this section dealing with high-level language interface require 
a prior knowledge of the language specifications for the given 
high-level language. 

The intended audience for the section entitled "INSTALLATION GUIDE" 
are the people involved with the preparation for and the installation 
of the Special Real Time Operating System PRPQ. Users of this section 
should have prerequisite knowledge of OS/VSl system programming, job 
control (JCL) e SYSGEN, and generally a thorough knowledge of OS/VSI, 

The final section entitled "OPERATORS' REFERENCE" is intended for the 
system console operator. This section contains operations information 
to enable the operator to start, terminate, and communicate with the 
Special Real Time Operating System, The operator should be familiar 
with OS/VSI operating techniques. 
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CHAPTER 1. GENERAL INFORMATION 



INTRODUCTION 

The Special Real Time Operating System PRPQ is a support program that 
augments the services of 0S/VS1 to support realtime applications and 
provides a stable operating environment. The services provided by 
0S/VS1 are still available to a program or system of programs utilizing 
the Special Real Time Operating System- Although in some cases, the 
Special Real Time Operating System acts as an interface between 0S/VS1 
and user programs, as shown in Figure 1-1. 




Figure 1-1. -User Special Real Time Operating System-OS/VS Interface 

The installation of the Special Real Tinae Operating System on the user's 
0S/VS1 system entails no modifications to the 0S/VS1 system; although 
there are certain additions to that system. In particular, there are 
supervisor call (SVC) routines that must be included into the 0S/VS1 
libraries. The Special Real Time Operating System services augment 
the 0S/VS1 services in the following areas: 

• Lower overhead through independent task management 

• Significantly enhanced time management routines 

• Realtime message handler 

• Data base management and data base logging 

• Duplicate data set support for critical Special Real Time Operating 
System and user data sets. 

• Selective termination of units of work 

• Selective data recording for post -run analysis 

• Input message processing 

• High-level language support for PL/I and FORTRAN 

• Failover restart support. 

In addition to these enhancements, the Special Real Time Operating 
System is designed so that each user builds and tailors his own Special 
Real Time Operating System for his own equipment configuration and for 
his own operational requirements through a system build or system 
generation (SYSGEN) process. 

Creation and modification of the table structure and initial conditions 
for the online system are handled by offline utility programs. As a 
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result, changes in this area do not require additional system 
generations. 



GEN^PAL DESCRIPTION 

The Special Real Time Operating System is designed to enhance areas 
which are critical to a realtime operation. The following paragraphs 
discuss the enhancements which are provided by the Special Real Time 
Operating System. 

Independent task management allows a task to be created and remain in 
existence when its processing is finished. Units of work are queued 
to the task, and the task does its processing with the overhead of 
resource allocation, initiation, eind termination only once and not for 
any subsequent processing of units of work by the task. The Special 
Real Time Operating System task management routines bring a task into 
virtual storage, queue work against the task, and delete the task or 
specified units of work upon request from the user. This results in 
a significant decrease in task management processing overhead. Also, 
the Special Real Time Operating System provides the user with greater 
flexibility and control over the work to be processed by a given task. 

The Special Real Time Operating System time management services fall 
into two categories. First, the Special Real Time Operating System 
maintains system time and date independently of 0S/VS1 time and date. 
The Special Real Time Operating System time can be synchronized with 
an external time source or can be adjusted by manual inputs. Second, 
the Special Real Time Operating System time management services provide 
the user with the capability to pass a work request to a specific task 
at a selected time and, optionally, have the work request repeated at 
a specified interval. 

The realtime message handler allows messages which the user has 
previously defined offline to be accessed in realtime. These messages 
can then be selected by message number, modified, and routed in realtime 
with minimum impact on system performance. 

Th6 Special Real Time Operating System data base services maintain a 
data base in virtual storage and on direct access storage. The services 
also allow the data base to be accessed independently by several tasks. 
The data is defined as a group of named arrays and named items within 
the arrays. The data is accessed by name, and this allows associated 
programs to be coded independently of most changes or additions to the 
data base. The content of the data base arrays may be logged to history 
files on a cyclic or demand basis. The logged data can then be used 
for reinitialization of the data base after a system outage as well as 
a historical record of system operation. The data base arrays and 
items are created by an offline utility program for use in the realtime 
run. 

Duplicate copies of the critical Special Real Time Operating System 
and/or user data sets can be maintained to provide backup copies should 
the primary copy experience a failure. This provides a smooth 
transition when making modifications to these critical data sets. The 
duplicate data set support services are optional and may be selected 
when the Special Real Time Operating System is created. Duplicate data 
sets may be used to keep backup copies of the data bas« data sets. 

The impact of failing 'casks is minimized through selective termination 
of units of work. If a task experiences a failure while executing a 
unit of work, that unit of work is terminated. However, the task is 
maintained, and all remaining units of work queued to the task will be 
executed. 
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The Special Real Time Operating System record and playback feature 
provides services for the user to define data that can be recorded on 
tape or direct access device during realtime execution. This recorded 
data can then be used for post-run analysis or as test data on a 
subseguent program execution. 

An input message processor is provided to allow for operator 
communication. This allows operator commands to be entered through a 
system console and routed to designated user programs. 

An interface is provided so that the user may code his programs in PL/I 
or FORTRAN and request the normal Special Real Time Operating System 
services through the interface program. 

The Special Real Time Operating System has facilities to allow execution 
on a two CPU configuration where a job in the backup CPU monitors the 
performance of the online CPU. When either CPU recognizes that a 
failure has occurred, that CPU can request a failover, and the backup 
CPU becomes the online CPU. Failover can also be initiated by program 
request to facilitate scheduled maintenance or changes to the 
operational environment. 

CUSTOMER RESP ONSIBILITES 

It is the customer's responsibility to provide in his installation: 

• Facilities and minimum hardware configuration required for the 
Special Real Time Operating System 

• Ordering, generation, and testing of the host 0S/VS1 system 

• Ordering, generation, and testing of the Special Real Time Operating 
System 

• Processing programs required for the realtime operation 

• Ordering, generation, and testing of any related PRPQs or program 
products to be installed 

• Data set contents for defining initial values, limits, and other 
control parameters 

• A thorough knowledge of his system and his desired control strategy 

• Orders for required computer and terminal equipment needed in the 
system 

• Installation of any instrumentation and/or common carrier facilities 
required to meet his desired control strategy 

• Design and implementation of any specialized application programs 
and/or display formats required to meet his control strategy 

• Training of personnel 
PROGRAMMING SYSTEMS 

All Special Real Time Operating System programs are coded using the 
System/370 Assembler Language. The Special Real Time Operating System 
executes under control of IBM Operating System/Virtual storage 1,. 
Version 3-0 or a later release. The following components of 0S/VS1 
are required: 
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• Supervisor 

• Sequential Access Method 

• Direct Access Method 

• Linkage Editor 

• Loader 

• System Assembler 

• System Utilities 

• Partitioned Access Methods. 

In addition to the 0S/VS1 components, the user may require any of the 
following : 

• Z (360S-NL-511 ) and PL/I F Subroutine Library (360S-LM-512 
VS1) 

• PL/I Optimizing Compiler - 57 34-PL1 

• PL/I Opti mizing Compiler and Libr arie s - 5734 - PL3 

• PL^I_I§sident_Library - 5734- LMU 

• PL^I_l£ansient_LibrarY - 57 34-LM5 

• F0EOM_IV (G1) - 5734-F02 

• EORTRAN_IV_Librari - 573U-LM1 

• fORTRAN_IV (H Extended) - 573a-F03 

• FORTRAN-! V_Librari - 5734-LM3. 



SYST EM CONFIGURATION 

The following minimum configuration is required to compile and execute 
the Special Real Time Operating System. 

The machine configuration for the Special Real Time Operating System 
varies according to the user's application needs. Typical systems are 
shown as a guideline: 

• For Compilation - A 3135 Processing Unit Model DH (245,760 bytes) 
and appropriate system console. Sufficient Input/Output (I/O) 
devices must be included to support the requirements for system 
input, system output, system residence, and system data sets. 

• Minimum Operational System - A 3135 Processing Unit Model H 
(245,760 bytes) including one byte multiplexer channel, one block 
multiplexer channel, and floating-point instruction set. The 
configuration must include sufficient I/O devices to support the 
requirements for system output, system residence, and system data 
sets. Sufficient direct access storage must be provided to satisfy 
user information storage requirements. Direct access devices may 
be chosen from a 2305 Fixed Head Storage, a 2319 Disk Storage 
Control (Integrated), a 3330 (3333) Disk Storage F^acility, 3340 
Disk Storage Facility, or combinations. 
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A magnetic tape unit (9-trac)c) must be available for program 
distribution and maintenance. 

Storage requirements for the Special Real Time Operating System are 
presented below. The figures are approximate and assume a typical 
customer environment. They are intended as a guide only. 



STORAGE IISUIMILENTS 

Figure 1-2 shows the approximate Virtual Storage required by the load 
modules which comprise the Special Real Time Operating System. The 
total size represents the approximate maximum number of bytes of storage 
required for all load modules of each function. Several functions are 
selectable by Special Real Time Operating System SYSGEN which may reduce 
the total size of any SYSGENed system from these values. The table 
includes estimates for routines which are used in an offline environment 
only and will never be a part of the online system- Some of the 
routines may be a part of the online system during initialization for 
a short duration when requested by the user or while processing unusual 
conditions. 

The frequently used column represents the approximate number of bytes 
of each function which may be used frequently in most systems during 
a continuing realtime execution. The actual use of any function is 
dependent upon the application programs and as such, the amount of 
virtual or real storage occupied by any function is predictable only 
through analysis of the application. 

In addition to the storage represented in Table 1, approximately 320 
bytes are added to the 0S/VS1 fixed nucleus, and 7700 bytes are added 
to the pageable nucleus. 

The Special Real Time Operating System programs also require 
approximately five cylinders of a 3330 direct access storage device 
(or equivalent) . 

These figures do not include virtual storage or direct access storage 
which are required for the user's data base. 
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Function 


Frequently Used 


Total Size 


Task Management 


5,000 


1 1 ,000 


Time Management 


3,000 


5,000 


Data Base 


4,000 


5,000 


Data Base Logging 




6,000 


Message Handler 


3,300 


3,300 


Data Recording 




7,000 


Report Data Output 




900 


Duplicate Data Set Support 


5,000 


22,000 


Input Message Processing 




7,400 


System Initialization 




41 ,000 


Failover/Restart 


1 ,000 


20,000 


FORTRAN PL/I Interface 




2,000 


Offline Utility Routines 




35,000 



*Specifies functions wich are optionally selected by the user when he generates his Special 
Real-Time Operating System. 

Figure 1-2. Storage Reguirenents 
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IIMING INZOFM ATION 

The timing information given here is meant to aid the user in evaluatin 
factors which may impact the performance of the Special Real Time 
Operating System. Timings were obtained on a Release 3.0 version of 
OS/VSl with eight megabytes of virtual storage and System Management 
Facility (SMF) . The following was the basic hardware configuration: 

• System/37 0 Model 145 

• 512K bytes of main storage 

• Four 3330 direct access storage devices. 

While timing statistics were being gathered, no other jobs were 
executing. The Special Real Time Operating System was generated with 
the following options: 

• Two-partition support 

• Duplicate data set support 

• Failover/restar t. 

The test data base consisted of U6 arrays. Of these arrays, 5 were 
loggable and 12 were direct access storage resident arrays (this 
includes 5 log arrays). Of the loggable arrays, 4 were refreshed durin 
initialization. 

The following chart gives approximate timings for the major Special 
Real Time Operating System services. The timings all include OS/VSl 
control program services. Task management timings do not include the 
time of execution of the test program. Times are given as CPU time 
and as such do not represent elapsed time. The elapsed time could vary 
greatly depending on system activity, paging, I/O activity, device 
types, etc. 

Caution and judgment should be used in evaluating these statistics due 
to the many OS/VSl SYSGEN options and other variables involved. The 
statistics must be interpreted only as the results obtained in the 
environment described, and not as a commitment to be met in any or all 
environments. All times are shown in millisecond units (ms) . 
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INITIALIZATION 



Basic Jobstep Initialization 900-1200 a 
(includes task management initialization) 

Time Management Initialization 125-150 ms 

Data Base Initialization* 1500-up ms 

Logging Initialization ♦* 425-up ms 
(includes data base refresh) 

Supplementary Services *** 900*up ms 
(includes Message Handler & Duplicate Data 
Set support) 



TASK MANAGEMENT 

PATCH to existing independent task for a 3.70-5-0 m 

reentrant load module previously loaded 

PATCH to existing independent task for a 60-100 ms 

reentrant load module not previously loaded 

PATCH to existing independent task for a 50-100 ms 

non- reentrant load module 



PATCH to dependent task (or non-existing 25-75 ms 

independent task) for a reentrant load module 
previously loaded, assuming there were no 
dormant Special Real Time Operating System 
tasks available 



♦Dependent upon size of data base. 



♦♦Dependent upon number of log arrays and initialization 
refresh options. 

♦♦♦Dependent upon number of messages and the number of 
duplicate data sets. 

PATCH to dependent task (or non-existing 20-75 ms 

independent task) for a reentrant load module 
previously loaded, assuming a dormant Special 
Real Time Operating System task is available 

PATCH to dependent task (or non-existing 65-100 ms 

independent task) for a reentrant load module 

not previously loaded, assuming a dormant 

Special Real Time Operating System task is 

available 



PATCH to dependent task (or non-existing 70-150 ms 

independent task) for a reentrant load 
module not previously loaded, assuming 
there were no dorm an t Special Real Time 
Operating System task available 



PATCH to dependent task (or non-existing 75-155 ms 

independent task) for a non-reentrant load 
module, assuming there were no 
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dormant Special Real Time Operating System 
tasks available 

PATCH to dependent task (or non-existing 70-150 ms 

independent task) for a non- reentrant 
load module, assuming a dormant Special 
Real Time Operating System task is available 

REPATCH SVC 1-5 ms 

DPATCH SVC 6-2.5 ms 



TIME MANAGEMENT 

TIME - update time array routine 3-5 ms 

PTIM - execute PATCH routine 6-15 ms 

PTIME SVC 5-10 ms 



DATA BASE* 

GETARRAY/PUT ARRAY 

TYPE=ADDR 2.5-5.0 ms 

TYPE=SPEC 15-40 ms 

TYPE=DATA 2,75-5.0 ms 

GETITEM/PDTITEM 

TYPE=ADDP 15.0-55*0 ms 

TYPF=SPEC 15.0-55.0 ms 

TYPE=DATA (address given) 3,0-5.0 ms 

TYPE=DATA(no address given) 15.0-55.0 ms 

GETBLOCK/PUT BLOCK 

VS resident 2.0-3.5 ms 

DA resident 10-20 ms 



DATA BASE LOGGING** 
PUTLOG 

NORMAL 13.0-40.0 ms 

LOGHDR 22.0-65.0 ms 

BLKLST 10.0-30.0 ms 

GETLOG 14,0-100 ms 

DUMPLOG 200- up ms 



SUPPLEMENTARY SERVICES 

CHAIN 0. 5-1. 5 ms 

DEFLOCK 2.5-5.0 ms 

LOCK 0. 1-0. 5 ms 

GETWA 0.45-1-0 ms 

MESSAGE HANDLER (includes PATCH) 30-50 ms 
DUPLICATE DATA SET 

DDS READ/DDSWRITE 12-50 ms 

DDS CHECK 7-25 ms 

DDSPOINT/DDSFIND 5-20 ms 

DDSBLDL 20-60 ms 



GENERAL INTORMATION 1-9 



'•'Dependent upon size of data base and number of ITEMS being processed. 
♦ t^Dependent upon number and size of log arrays and nunber of log copies. 
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CHAPTER_2i APPLICATION SERVICES 



INTROpOCTION 

The objectives of the Special Real Time Operating System in a real-time 
environment are to provide additional services to user coded, real-time 
programs and to minimize the impact normally caused by ABENDing 
programs. The additional services are provided for lower supervisor 
overhead and added capabilities and flexibility in the areas of task 
management, time management, data base, message handling, and failover 
restart, as well as other less significant enhancements. Minimizing 
system impact due to ABENDS is accomplished by isolating user tasks 
from one another and by handling work requests as separate entities 
from the user programs. 



GENERAL DESCRIPTION 



The Special Real Time Operating System, by itself, as a real-time 
program, does meaningful processing only when its services are requested 
by user programs in a real-time environment. The Special Real Time 
Operating System services are requested through the use of macro calls 
which invoke the Special Real Time Operating System SVC routines or 
branch to the Special Real Time Operating System subroutines. This is 
shown in Figure 2-1. 




SVC Routines 



Branch to .Subroutine 
X — 



Task 
Mgmt 



Time 
Mgmt 



Failover 
Restart 



Data 
Base 



Message 
Handler 



Duplicate 
Data Set 



Data 
Record 
and Play 
Back 



High Lvl 
Language 
Interface 



Figure 2-1. The Special Real Time Operating System Overview of the 
Online System 

Figure 2-1 shows the major areas in which the Special Real Time 

Operating System supplies services for real-time execution 

The task management services provide facilities to create the real-time 
task, queue work to an existing task, or delete a task. These services 
are provided to the user through the PATCH, REPATCH, and DPATCH macros. 

Time management services allow for maintenance of time and for causing 
work to be passed to tasks at a given time or cyclically for a given 
interval. The time management services are available to the user via 
the PTIME macro. 



For a real-time environment, the system must have the ability to recover 
quickly from a failure or system outage. The Special Real Time 
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Operating System failover restart services allow for a fast switch to 
a backup-CPU (failover) or a fast restart in the failing CPU. These 
services are either automatic or under operator control. The data base 
services in the real-time application allow the user to access the data 
base but prevent (when requested) access to data by one program if that 
data is currently being modified by another program. User access to 
the data base is achieved through six macros; GETITEM, POTITEM, 
GETBLOCK, PUTBLOCK, GETARRAY, and POTARRAY. 

The data base, or portions of it^ may be logged at given intervals to 
create a history file. The user interface to the logging routines is 
through the GETLOG, PUTLOG, and DUMPLOG macros. 

The real-time message handler provides a service whereby predefined 
messages may be retrieved, modified, and routed to predefined devices 
in real-time. The user interface to this service is through the MESSAGE 
macro. 

Duplicate data set support provides a service whereby the user can 
maintain duplicate copies of critical data sets. The user requests 
this service via the DDSBLDL, DDSCLOSE DDSDCB, DDSFIND, DDSOPEN, and 
DDSSTOW macros. 

Data record and playback provide a facility for the user to record 
areas of virtual storage under program control and later to retrieve 
or play back the data. The user requests data to be recorded via the 
RECORD macro. 

The high-level language interface programs provide an interface for 
the real-time services to be used from a PL/I or FORTRAN program. 

Each of the Special Real Time Operating System services shown in Figure 
2-1 is described in detail in the following sections. Additional 
services are described later. For the convenience of the application 
programmer, all online macros are described in detail in the section 
entitled 'Special Real Time Operating System Online Macros'. The macros 
in this section are listed in alphabetical sequence. 
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TASK MANAGEMENT 

The Special Real Time Operating System task management services are an 
extension of the 0S/VS1 task supervision and virtual storage supervision 
to make more efficient use of system resources in a real-time processing 
system. These additional services are provided by the Special Real 
Time Operating System through the use of SVC routines, monitor routines, 
and service subroutines. This is shown m Figure 2-2. The service 
subroutines can be used only by the SVC routines and the monitor 
routines. The user invokes the monitor through the SVC interface. 
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Figure 2-<'2. Task Hanageiest OYecvlev 



The Special Real Tiae Operating Systea utilizes many tasks (TCBs) during 
online execution. The task structure for the permanent TCBs is 
established during initialization. Figure 2-3 shows the Special Real 
Tile Operating Sy^tea task structure and the task's relative priorities. 



□ 



0 



■if- 



□ 



Q 



DPPTPMON 
PRTY-0 



DPPTPMON 
PRTY-0 



□ 



OPPTSMON PRTY«J08STEP 



Ql □ 



□ 



DPPXIMPW 
PRTY- 
X)BSTEP 3 



DPPCTIME 
PRTY- 
JOBSTEP t 



DPPCPTIM 

PRTY- 

JOBSTEP-2 



OPPMMSGI DPPDFREO 
PRTY- PRTY= 
JOBSTEP-3 JOBSTEP-a 



Figure 2-3. 
Priorities 



The Special Heal Time Operating System Task structure and 



Task DPPTSHOH receives control from initialization via 7CTL. There 
will be a variable number of tasks for DPPTPHON. The number will depend 
upon SYSGBH options. Following initialization these advance TCBs will 
have a dispatching priority of zero and a limit priority of JOBSTEP 
task tiinus three (JOBSTEP-3) , which is the highest available user 
priority. 

The task for the input message processor program (DPPXiMPW} is 
established with a dispatching priority of JOBSTEP-3. Time management 
(DPPCTIHE) has a priority of JOBSTEP- 1» and the PTIME monitor (DPPCPTin) 
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has a priority of JOBSTEP-2. The real-time message handler program 
(DPPHMSGI) is PATCHed with a priority of JOBSTEP-3. 



If cyclic logging (DPPDFBEQ) were selected during system generation, 
the cyclic logging program would be invoked at initialization time and 
would have a TCB with the priority of JOBSTEP-3. Demand logging does 
not create a TCB at initialization. 

The tasks used by the Special Real Time Operating System are true 0S/VS1 
tasks and will be assigned OS task priorities based upon the priority 
of the jobstep task. These tasks compete for resources among themselves 
and with tasks of other jobs in the system based on their assigned 
priority. When two or more tasks have the same priority, the order of 
assignment to that priority value determines which task will be serviced 
f irst . 



PiXCH/FEPAlCH 

PATCH is the service by which a task is created or by which a work 
reguest is made for a task already in existence. REPATCH is the means 
by which a failing PATCH may be retried. 

To provide its services, the Special Real Time Operating System builds 
control blocks and tables which it uses to maintain control of the 
system and to interface with user programs. Figure 2-4 shows the 
relationship of the Special Real Time Operating System control blocks 
for the first PATCH issued on a basic Special Real Time Operating System 
system, when the user gains control. The Special Peal Time Operating 
System builds its control blocks in protected storage and allocates it 
via an internal routine called CBGET (control block get). This storage 
is allocated at initialization and is not expandable. 
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Figure 2-U. Task Management Control Blocks 

At the point that prograa ONE gains control following the PATCH, general 
register 1 will point to the three words in the TCBX (TCB extension) 
containing pointers to the XCVT, the resource table, and the parameters 
being passed into prograa OME. The XCVT is the Special Real Tine 
Operating System equivalent to the OS CVT. The XCVT contains pointers 
and control information which must be available to the subsystems as 
well as the Special Real Time Operating System- The SCVT contains 
pointers to system areas and control information which must always be 
available to the Special Real Time Operating System. The Task 
nanagetaent Control Table (TJICT) contains task-oriented information 
which must be available to all the Special Real Time Operating System 
tasks. The TCBX contains control information pertinent only to the 
specific task and contains a pointer to the XCVT. This pointer links 
each tisk to the basic Special Real Time Operating System control 
information . 

The resource table is an 8-byte area of virtual storage that the Special 
Real Time Operating system gets from subpool zero and passes to the 
user. This area can be used by the user to pass information across 
PATCHes to the same task. For example, two PATCHes could be performed 
for TASK=A, one for BP«A and the second for EP=B. Program A could open 
a DCB and put its address in the resource table. When program B 
executes, it could do I/O processing using the open DCB. The resource 
table is initialized to contain zeros when the task is created and is 
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not changed by the Special Real Time Operating System as long as the 
task is in existence. 

The work queue element (WQE) is built by the Special Real Time Operating 
System to represent the PATCH request for execution of program ONE 
under task FIRST. Once program ONE has completed execution and returned 
control to the Special Real Time Operating System, the WQE is deleted. 
If additional PATCHes had been made for task FIRST, additional WQFs 
are queued to the TCBX. When the first execution of program ONE is 
completed, the first WQE is removed and the second scheduled. This 
process continues until there are no WQEs left on the queue. There is 
one WQE created for every PATCH. 

The load control block (LCB) is created by the Special Real Time 
Operating System to represent the load module for program ONE. Program 
ONE in Figure 2-H is represented by two LCBs. This is the case when 
the program is reentrant. A non-reentrant module is represented by 
only one LCB chained to the requesting WQE. There is ona LCB for each 
module (EP«) under each task (TASK^), plus one LCB for each reentrant 
module i^i the partition. LCBs are created for modules loaded through 
the use of the Special Real Time Operating System servicas. Figure 6 
shows the Special Real Time Operating System LCB-WQE blocks that will 
be built for the following PATCHes: 

EXAHPLE 1: 



PATCH 1 
PATCH 2 
PATCH 3 
PATCH 4 
PATCH 5 
PATCH 6 



PATCH 
PATCH 
PATCH 
PATCH 
PATCH 
PATCH 



TASK=X,EP=A 
TASK=X,EP-B 
TASK=Y,EP=A 
TASK-X,EP=B 
TASK=Y,EP*B 
TASK=Y,EP«A 



(reentrant) 

(non-reentrant) 

(reentrant ) 

(non-reentrant) 

(non-reentrant) 

(reentrant) 
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Figure 2-5. Control Blocks Built for Example 1 

The control blocks will be built as shown in Figure 2-5 at a point in 
time when all PATCHes have been issued, and program A and B are 
executing, under the first WQE. 

PATCH 1 causes a WQE to be scheduled for program A on task X. PATCH 
1 also creates the LCB pointed to by the WQE and the LCB pointed to by 
the TMCT. 



PATCH 2 creates the WQE and its LCB for task X, program B. 

PATCH 3 creates the WQE on task Y and the LCB for program A pointed to 
by the WQE. It also points the LCB to the existing LCB for program A 
on the TMCT. 



PATCH 4 creates the WQE for task X and points it to the LCB for program 
B that was previously created by PATCH 2. 

PATCH 5 creates the WQE for task Y, and because this is the first 
request for program B on task Y, creates an LCB for B and chains it to 
the WQE. 

PATCH 6 creates a WQE for task Y and points it to the LCB previously 
created by PATCH 3. 

The Special Real Time Operating System task management is initialized 
by DPPINIT. DPPINIT gets protected core from subpool 253 and builds 
the XCVT, the SCVT, and the TMCT. It then initializes the get work 
area (GETWft) and control block get (CBGET) storage. Next, 
initialization determines the number of TCBs and task control block 
extensions (TCBXs) to be obtained and initialized, and creates the TCBs 
by attaching the PATCH monitor (DPPTPMON) for the number of TCBs. Next, 
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DPPINIT gets CBGET storage for TCBXs, chains the TCBX to a TCB, and 
puts the TCBX on the TMCTFREE chain. When initialization is completed, 
it XCTLs to the system monitor (DPPTSMOM) , At this point the system 
is configured as shown in Figure 2-6. 
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Figure 2-6. Control Blocks After Initialization 

When DPPTPMON is in storage and begins execution, it waits until it is 
posted by DPPINIT. DPPINIT posts DPPTPMON when a TCBX has been 
initialized and chained to the TCB. DPPTPMON then does a GETMAIN for 
the resource table, and chains it to the TCBX- A STAE macro call is 
then executed by DPPTPMON specifying load module DPPTSTAE as the STAE 
exit routine. DPPTPMON then executes a WAIT macro call. At this point 
the Special Real Time Operating System is ready for user service 
requests. 

The user requests that a task be brought into virtual storage and 
executed via the PATCH macro. Two different types of tasks can be 
executed. Dependent tasks operate similarly to normal 0S/VS1 tasks; 
the requested module is loaded and executed once; then the module is 
deleted, and the tiask is terminated. Independent tasks, however, can 
request loading of multiple programs; each can be executed many times 
and is terminated only upon a specific request from a user by the DPATCH 
macro. To facilitate multiple execution of independent tasks, the 
Special Real Time Operating System loads each reentrant program only 
for the initial PATCH. The WQE and LCB are built and queued to the 
tasks TCBX. On subsequent PATCHes to the same task requesting the 
execution of the same program (EP=) , a WQE will be created; but the 
program will not be reloaded, and the WQE will be pointed to the LCB 
created by the first PATCH. 

An option on the PATCH macro allows programs to be deleted after the 
WQE has been processed, even though the program is reentrant. 
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The user's PATCH lacro results in the PATCH S?C code (DPPTPSVC) gaining 
control. The SVC validity chec)ts the input paraaeters, and if they 
are valid, obtains a TCBX and a TCB for the task. DPPTPSVC then builds 
a MQE and an LCB for the program and chains them to the TCBX. DPPTPSVC 
then posts DPPTSHON to change priority (CHAP) of the TCB to the 
specified priority (PHTY=) and returns control to the program that 
issued the PATCH SVC. 

The system monitor (DPPTSMON) has three main functions. 

• When posted by DPPTPSVC, it CHAPs the TCB to the requested priority. 

• It creates TCBs and TCBXs and maintains them on the TMCT chain. 

• DPPTSHOK handles the loading and deleteing of reentrant modules. 

The PATCH monitor (DPPTPMON) is the special Real Time Operating 
System-user interface, DPPTPMOM manipulates WQEs and non-reentrant 
LCBs. DPPTPHON is the program under vhich all user tasks are executed. 
When the program has been loaded and the WQE scheduled, DPPTPHON 
branches to the user code. Upon completion, the user executes a normal 
BB14 return, and DPPTPttOM regains control, posts the user ECB, and 
attempts to schedule the next «QB. If no WQEs exist, DPPTPHON waits 
for the next PATCH. 

Note: Because user {urograms are loaded and branched to by DPPTPHON, 

the usee program vill not be represented by an BB on the 0S/VS1 
system. As a result, user programming errors will cause ABEND 
dumps that shorn DPPTPHON as the ABENDing program. 

The following examples show how the user would invoke the Special Seal 
Time Operating System task management services through the use of the 
PATCH macro. 

PTCH01 PATCH TiSK«0NE,EP«PIBST,Ql«3, * 

QPOS«PIRST,PSTT» (TM0,4) , * 
ECB" (ECBONE) , * 
FHBB»P,ID«t» 

This PATCH will cause a task with the name ONE to be created. If task 
ONE already exists, a WQE will be queued to it to represent PATCH 
PTCH01. PTCH01 is a request for execution of program FIRST, and the 
WQE will be queued at the top of the queue (QPOS=FIRSt) • If the task 
does not exist, it will be created with a priority of 4 less than the 
existing task named TWO and will allow a maximum of three WQEs (QL=3) 
to be queued plus the current tQB being processed. If task TWO does 
not exist, the PATCH will not be processed, and the PATCHor will be 
given a return code 10. If task ONE does exist, the QL and PRTY 
keywords will have no effect. The ECB^keyword specifies that an ECB 
at location ECBONE is to be posted when the Special Real Time Operating 
System task management dequeues the WQE which represents this PATCH 
request. The ECB will be posted with a Special Real Time Operating 
System task management POST code in the high-order byte and the 
low-ordei: three bytes of register 15 if the PATCHed program is completed 
successfully, or the ABEND code is in the low-order three bytes if the 
task ABBNDed. FBEE^P reguests that the Special Real Time Operating 
System task management services free (FREBHAIN) the virtual storage 
ocrupied by the PROBL (user problem parameter list). The ID=4 requests 
that a value of 4 be put into the PROBL and passed to the PATCHed 
program. 
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PTCH02 PATCH ID=255 ,TASK«BAIN 

BP«iOBK01,PRTT«(,1) , 
QL«9 



PTCH02 uses the special ID (ID«255). This ID creates a Special Peal 
Tine Operating Systen task naaed NAIN with a queue length o£ 9 and a 
priority of 1 less than the PATCH or. The program naaed WORK0 1 is loaded 
but never given control, because the ID is 255. This facility allows 
the user to create a task structure of reentrant and serially reusablt; 
prograas. As a result, he knovs the task structure prior to the 
execution of the PATCHed tasks. 

Reentrant and serially reusable programs are kept in virtual storage 
and are not deleted at completion of their execution. If the user 
wishes to have a reentrant or serially reusable prograa deleted at its 
coapletion, he must code the PATCH with EP« (name, DELETE). This will 
result in the LCB for the prograa being removed from the task's LCB 
chain, and if no other tasks have issued PATCHes for the program, the 
load module will be deleted. However, if other tasks did PATCH the 
program and did not request the DEIETE option, the load module will 
not be deleted. If multiple tasks PATCH a module and all specify the 
DELETE option, a use count is kept by the Special Real Time Operating 
System task management, and the module is deleted when the use count 
becomes zero. The Special Real Time Operating System use count is 
independent of OS/ysi use count. As a result, if a user program does 
a LOAD, followed by PATCH with EP=(name, DELETE) , the Special Real Time 
Operating System DELETE will not necessarily result in the module being 
removed from virtual storage, as the 0S/VS1 use count will not go to 
zero. This is because the Special Real Time Operating System task 
management routines will issue LOAD for the module on the first PATCH 
to it resulting in an OS/VSI use count of 2. 



WORK 2M®Sie Poolin g 

Work queue pooling is a capability of Special Seal Time Operating System 
to allow a single task to process work that would otherwise be processed 
by several tasks, or several tasks to process the work that would 
otherwise be processed by a single task, or combinations thereof. A 
close similarity to this concept can be observed in the OS/VSI job 
scheduler where an initiator can process work from several job classes 
or jobs of a given class can be processed by any of several initiators. 

Work queue pooling may be invoked for a given execution of the Special 
Real Time Operating System by including in the initialization stream 
the commands which define the elements. Queue Holders (QH) and Queue 
Processors (QP) , to be active on this execution. To make use of work 
queue pooling, the user will execute PATCHes to the queue holders, 
exactly as done to independent task. One command (card) will define 
one QH or QP. The QP represents a Special Real Time Operating System 
and OS task, the same as with an independent task. I t is defined at 
initialization and will remain for the duration of the job. There is 
no provision for adding or deleting QPs after initialization. The QP 
differs from an independent task in that work cannot be passed directly 
to the QP via a PATCH, 

The QH appears as an independent task without an associated OS task. 
Work is passed to the QH via PATCH but the work is processed by one of 
the QPs associated with the QH. The QH has a name, exactly as an 
independent task and the TASK* operand of the PATCH and other macros 
will reference the QH by this name. As with QPs, all QHs must be 
specifiei at initialization. When specifying QHs, the user assigns 
the name and other attributes. Any QH may be specified to be connected 
to several QPs; that is, any of the connected QPs are allowed to process 
work that is 'PATCHed' to this QH . Also, several QHs may be connected 
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to any one QP , which means that a QP can process work from any of 
several QHs. There is an implied priority relationship in this scheme 
in that when a QP completes a piece of work, it will look for work in 
the first QH connected to it and only if that QH is empty will it look 
to the next QH, etc. The opposite is also true when a piece of work 
is passed to a QH, the work will be given to the first QP that is 
connected to it and is not busy. If all connected QPs are busy, the 
work will be queued to the QH to await a QP that becomes available. 

The relationships between QPs and QHs is defined through the 
initialization stream" commands. The QP command allows the user to 
specify the order in which the QP is to search the QHs for new work 
when a piece of work is completed. The ordering of the QP commands 
implies the order in which to search for an available QP when work is 
added to a QH . Each QP is assigned a number (0 to 99) on the OP 
command. From this number a name is generated. The user 
assigned number will be used for all references by other commands. 
Each QH is assigned a name (1 to 8 EBCDIC characters) by the QH command- 
This name will be used for all references to it, either by other 
commands or by programs via the PATCH macro, etc. Various other 
parameters may be specified on the QH and QP commands.. The PRTY* 
parameter on the QP coiamand is similar to the same parameter on the 
PATCH command. The HOLD=YES parameter allows the QP to be initialized 
in a hold status which meands that it will aot process any work until 
a release is entered through the IMP commands provided. 

The QL= parameter on the QH command specifies the number of work queues 
that can be stacked for this QH, similar to the same parameter on the 
PATCH command. The parameter SEQ=YES specifies that only one QP may 
be processing work from this QH at any time. The HOLD=YES parameter 
specifies that no work is to be processed from this QH- The PATCH=NO 
parameter specifies that the PATCH processor is to reject all PATCHes 
to this QH. The SEQ=, HOLD= and PATCH= parameters can be modified 
during execution through the IMP command processing provided. 

The inclusion of work queue pooling on a given execution of Special 
Real Time Operating System does not effect independent or dependent 
task operations. When a PATCH is executed, the PATCH code will search 
for a TCBX with the task name equal to that specified on the PATCH. 
If the name is not found or a name is not specified (dependent tasJc) 
a Special Real Time Operating System task is created and the work queued 
to the new task. If the name is found, the work is added to the work 
queue of the TCBS. If the TCBX is a QH, the work participates in the 
queue pooling. 

The user of Work Queue Pooling has the ability to determine the status 
of and control certain functions of the QPs and QHs through the IMP 
command processor. The user can hold or release either a QP or QH. 
If a QP is held, it will not accept any new work. If a QH is held, 
the QP (s) will not take work from it. The user can set a QH to be 
sequential or non-sequential. In the sequential state, only one QP 
may be processing work from this QH at any time. Non-sequential is 
the normal state where all connected QPs may be processing work from 
this QH simultaneously. The QH can be set to a PATCH or NOPATCH state. 
In the NOPATCH state all PATCHES to it will be rejected. PATCH is the 
normal state. In addition to changing one of the above conditions, 
the command can cause all work to be specified QH to be purged. 

The IMP command can cause Special Real Time Operating System messages 
to be output to report the status of these states as well as other 
information about the QPs or QHs. This information will include the 
element (QP and QH) name, the names of the elements connected to it, 
and the number of work queue elements awaiting processing. 
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When a program receives control as the result of a PATCH, Register 1 
contains the address of a 3 vord table. The second vord of this table 
contains the address of a resource table. If the progran is executing 
under control of a QP, this resource table is associated with the QP. 
Every program that is PATCHed to execute under a given QP will receive 
this sane resource table. In addition, register 0 will also contain 
the address of a resource table, if the program is executing under 
control of a QP, this , resource table will be associated with the QH 
from which the work was taken. This means that all programs which 
execute as the result of a PATCH to a given QH will have access to the 
same QH resource table. Caution must be exercised by the user if the 
QH is connected to two or more QPs, since several programs may be 
competing for this resource table. If the program is executing under 
Special Real Time Operating System task (not a QP) register 0 will 
contain the same address as is in the second word of the table addressed 
by register 1 . 

The following example shows how QP and QH statements in the SYSINIT 
input stream can be used to define two queue processors and two queue 
holders. All other control statements in the input stream have been 
omitted. 

//SYSINIT DD 



In this example both queue processor 19 (QP19) and queue processor 2 
(QP02) have been created to process work from (lueue holders DPPQABC 
and DPADHNO. However, since in the QP statement for QP19, queue holder 
DPPQABC has defined first, QP19 will give it a higher logical priority. 
Since the inverse is true in the other QP statement, QP02 will process 
the work from DPADHNO before processing work from DPPQABC. 

Assume the following PATCH macro calls are executed to route work to 
the queue holders. 



A 


PATCH 


TASK=DPPQABC,. . 


B 


PATCH 


TASK=DPADMNO,. . 


C 


PATCH 


TASK=DPPQABC,. . 


D 


PATCH 


TASK=DPPQABC,. . 


E 


PATCH 


TASK=DPPQABC,. . 



The resulting task/queue structure is illustrated in Figure 2-6.1. 
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QP 
QP 
QH 
QH 



19,QH= (DPPQABC, DPADM NO) 
2,QH= (DPADMNO, DPPQABC) 
DPPQABC 
DPADHNO 



QP19 



QP02 



A(DPPQABC) 



A{DPADMNO) 




A(DPADMNO) 



A(DPPQABC) 




Work Queue 




Figure 2-6,1. Task/Queue Structure 



QP19 will select work queue A from queue holder DPPQABC and 0P02 will 
sel3Ct work queue B from queue holder DPADMNO, Assume QP19 completes 
work queue A before QP02 completes work queue B. When QP02 completes 
work queue B, QP02 will attempt to select additional work from queue 
holder DPADMMO and, finding it empty, will select work queue D from 
queue holder DPPQABC. Upon completion of work queue D, QP02 will again 
attempt to select work from queue holder DPADMNO and, finding it still 
empty, will select work queue E from queue holder DPPQABC. 

Using a similar example to illustrate the functions of some of the 
optional parameters on the QP and QH statemtns, assume the following 
SYSINIT input stream was specified. Again only the QP and QH statements 
will be shown. 
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//SYSINIT 



DD 



QP 
QP 
QH 
QH 
QH 



19,QH= (DPPQABC,DPADMNO,DPPQXYZ) 

2rQH= (DPPQXYZ,DPPQABC) , PRTY= (JOBSTEP-0) 
DPPQXYZ,SEQ=YES,QL=10 
DPPQABC 

DPADMNO,HOLD=YES 



In the second example, queue processor number 19 (QP19) has been created 
with a default dispatching priority of the job step task minus 8 to 
process work queued in queue holders DPPQABC, DPADMNO, and DPPQXYZ and 
queue processor number 2 (QP0 2) has been created with a dispatching 
priority of the job step task minus 3 (the highest allowed to any user 
task) to process work queued in queue holders DPPZXYZ and DPPQABC (see 
Figure 2-6. 2) . 

Queue holder DPPQXYZ has been created as a sequential queue holder with 
a queue length of 10. Queue holders DPPQABC and DPADMNO have been 
created with default queue lengths of 255 (see Figure 2-6-2). DPADMNO 
has been held, that is PATCHes specifying a task name of DPADMNO will 
be accepted but neither queue processor (QP19 or QP02) will be permitted 
to select work from that queue holder. 
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QP19 



QPD2 




Figure 2-6.2. Queue Processor/Queue Holder Structure 

Now assume the following PATCH macro calls are executed to route work 
to the three queue holders. 



A 


PATCH 


TASK 


=DPPQXYZ,. 


B 


PATCH 


TASK 


=DPADMNO,. 


C 


PATCH 


TASK 


=DPPQABC,. 


D 


PATCH 


TASK 


=DPPQXYZ,. 


E 


PATCH 


TASK 


=DPPQXYZ,. 
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The resulting task/queue structure is shown in Figure 2-6.3. 



QP19 QP02 




Figure 2-6.3. Task/Queue Structure 

QP02, having the higher priority, will select work queue A from queue 
holder DPPQXYZ. QP19 will select work queue C from queus holder 
DPPQABC . 
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Assume QP19 completes work queue C before QP02 completes work queue A. 
QP19 will t ry to select additional work from queue holder DPPQABC first; 
(see Figure 2-6.4) but since all work for that queue holder has been 
exhausted, QP19 will then try to select work from queue holder DPADMNO. 
However, since DPADMNO was defined on the QH statement as being held, 
the work queue B cannot be selected by any queue processor. Therefore, 
QP19 will then attempt to select work from queue holder DPPQXYZ. Since 
queue holder DPPQXYZ was defined on the QH statement as being sequential 
and queue processor QP02 is currently executing a work queue from 
DPPQXYZ (work queue A), QP19 will be unable to select work from this 
queue holder either. Having searched for work on all queue holders 
that QP19 can process and having found none, QP19 will then be placed 
in a wait state. 



QP19 QP2 




Figure 2-6.4. Task/Queue Processing 

If a QS command of the form r xx, QS , A ALQH, REL were to be issued, then 
QP19 would then be allowed to select work queue B from queue holder 
DPADMNO. 



DPATCH 

The DPATCH macro is used to stop the processing of a specified task 
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and to cause the program to be deleted. Since the task may have several 
entries on its work queue, four types of DPATCHes allow flexibility. 

First, the TYPE=I causes the task to be DPATCHed immediately. The task 
is not allowed to complete the processing of the current WQE, but is 
ABTERMed. If ECB= was specified at PATCH time, the ECB is posted with 
the ABEND completion code hex'4C»- The ECBs for further HQEs are posted 
with a DPATCH completion (hex«42) . 

Second, the TYPE=D causes the task to be DPATCHed when the current WQE 
completes, and the ECBs for remaining WQEs are posted with a DPATCH 
completion. 

Third, TYPE=C causes the task to be DPATCHed only if there are no WQEs 
when the DPATCH request is received. 

Fourth, TYPE=W causes the task to be DPATCHed only when the work queue 
becomes empty. Additional WQEs can be added after the DPATCH request, 
and the DPATCH would only occur after the queue becomes empty. 

Fifth, TYPE=A causes the program being executed under the specified 
task to be ABENDed without deleting the task or any WQE's that may be 
awaiting execution. 

Note: If QPOS=DPATCH was specified on any one of the PATCHes to a 

given task, that WQE is scheduled, and the program executed at 
DPATCH time before the task is removed from the system. 



PURGEWg 

The Purge Work Queue Facility provides the capability of selectively 
purging work requests to a specified independent task. The selected 
work requests will be removed from the active work queue (i.e., a chain 
of work requests that have been generated in response to PATCH macro 
calls but have not yet been executed) or from the DPATCH work queue 
(i.e., a work request generated in response to a PATCH 
QPOS=DPATCH macro call). Other work requests for that task will 
not be purged but will be allowed to execute normally. 

PURGEWQ, on request, also notifies the user whenever the last of the 
selected work requests has been purged. 

The current work request (i.e., work request currently in execution 
for the specified task) will not be purged but will be allowed to 
complete normally eventhough it may be one of the selected work 
requests. PURGEWQ, in this case, will notify the user after the 
specified task has completed the execution of the selected work request. 
In addition to providing the synchronization of the completion (or 
purging) of selected work requests, PURGEWQ can be used in a "work 
shedding" environment as well. For example, work requests deemed to 
be of lesser importance can be selectively purged from the queue of 
work requests for a specified independent task to allow more time for 
the more important work requests to execute. The execution of a PORGEWQ 
macro call will not prohibit the scheduling of future work requests 
(PATCHes) to the specified independent task. PURGEWQ operates only on 
those work requests that have previously been scheduled. 



lEd of Task Ejcit Routin e 

The Special Real Time Operating System end of task exit routine (ETXR) 
is the program (DPPTETXR) that gains control from 0S/VS1 upon 
termination of a Special Real Time Operating System task. The ETXF 
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routine executes under the jobstep task (DPPTSMON) and cleans up after 
task termination. 



In the event that a task ABENDS, DPPTETXR issues a message through the 
real-time message handler specifying the task name and the failing 
program EP name. The TCBX is saved, and the TCB is detached. DPPTETXR 
also posts DPPTSMON to have the TCBX chciined to a new TCB. 

If the task is terminating normally, the TCB is detached. In either 
case, normal or abnormal termination, control of all locked resources 
is released and GETWA type AT areas are freed. 



STAE Processing 



Two STAE exit routines are used (1) to provide an interface to a user 
exit routine and to provide the Special Real Time Operating System with 
a DUMP/NODUMP facility upon abnormal termination of a subtask and (2) 
to allow cleanup functions to be performed when the real-time job step 
task is terminating. 



An initialization input stream command, STAEX, allows the user to 
specify the name of the user coded load module (exit routine) which is 
to be given control when any one of a list of load modules encounters 
an ABEND. A STAE is invoked for every Special Peal Time Operating 
System task so that when an ABEND occurs in one of the so specified 
load modules while executing under a Special Real Time Operating System 
task, including QPs, the exit routine will be given control before the 
DUMP/NODOMP decision is made by the standard Special Real Time Operating 
System STAE processor. Within the exit routine, the user may schedule 
a retry routine, force the ABEND to proceed with a dump or allow the 
Special Real Time Operating System STAE option in effect to determine 
if a dump is to be taken. 



On entry to the user exit routine, registers 0, 1, 13, 14 and 15 will 
contain the values as defined by OS/VSl STAE interface routines (see 
OS/ YS 1 Plan ning and U se r Guide, STAE macro instruction) . Register 2 
will contain the address of the TCBX for the abending task. In a queue 
pooling environment this will be the address of the QP TCBX. The user 
exit routine is limited by the same restrictions as a normal STAE exit 
routine. 



The DUMP/NODUMP facility allows control of System ABEND dumps for all 
load modules, for a group of load modules, or for an individual load 
module. This facility will not suppress user ABEND dumps. It is 
invoked by an entry to the Input Message Processor (IMP) of the form: 



r XX, STAE[ , SLAVE] 



r5M£ 

,NODUMP 
,ONEDUMP; 
,STEP 
, OPTION 



[ modulename, modulename, . . . ] 



The first positional operand, STAE, is required and defines the reply 
to the Input Message Processor as a command to the DUMP/NODUMP service 
interface routine. 



The second operand, SLAVE, is used by the Input Message Processor to 
route the command to the DOMP/NODOMP service routine in the SLAVE 
partition only. It is not a positional operand in that a null field 
(double comma) is not required to denote its absence. 
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Examples: 



r XX, •STAE,NOD0MP« 

This IMP command will cause all system ABEND dumps to be suppressed 
for the MASTER partition. 

r XX, • STAE, SLAVE, NODUMP' 

This IMP command will cause all system ABEND dumps to be suppressed 
for the SLAVE partition. 

The third operand is used by the DOMP/NODUMP service routine in 
establishing the options that will be in effect for those modules This 
operand is a positional operand, and its absence must be denoted by a 
null field (double comma) ; If omitted, the DUMP option will be assumed 
for. those modules specified in this reply. 

The valid options are: 

DUMP - allows a dump to be taken for these modules (provided 

there is a SYSDDDMP or SYSABEND DD statement). 

NODUHP - suppresses a dump from being taken for these modules. 

ONEDUMP - allows one dump to be taken for these modules (provided 
there is a SYSUDUMP or SYSABEND DD statement) then 
suppresses any more dumps for that nodule. 

STEP - ABENDS the job step if one of these modules ABENDS. 

OPTION - allows the operator to choose whether or not to take a 

dump following an ABEND of these modules. The operator 
is informed of the ABEND via a WTQR (message 850) and 
must reply 'YES* to receive the dump. 

The remaining operands, if any, are used to indicate the load module(s) 
that are to be covered by the specified option. A maximum of 10 load 
module names may be specified on any one reply- Null fields (double 
commas) will not be accepted. 

Example: 

r XX, •STAE,NODUMP« 

r XX, •SrAE,ONED0MP,MODA,MODB 

These two IMP commands will cause all system ABEND dumps to be 
suppressed for the MASTER partition except ABENDS for modules MODA 
and MODB. One dump will be taken for MODA on ABEND, and one dump 
will be taken for module MODB on ABEND after the command is entered. 

The use of a question mark (?) to terminate a load module name indicates 
that the specified option is in effect for all modules beginning with 
the portion of the name specified. The portion of the name specified 
must be at least one character and must not exceed seven characters. 
The modules are processed as a group and not as individual modules. 
This means that if the ONEDUMP option is specified with the module name 
DPP?, only one dump would be taken for the first module to ABEND with 
a name beginning with the three characters DPP. Dumps will be 
suppressed for any subsequent ABENDS for modules which have names 
beginning with DPP. 

Example: 

r XX, •STAE,NODDMP« 
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r XX, "STAErSTEP, MODDL? 



These two IMP commands will cause all system ABEND dumps to be 
suppressed for the MASTER partition except that a system ABEND from 
any module with a name beginning with MODOL will dump and will ABEND 
the entire jobstep. 

If no load module name is provided on a reply, the specified option 
will be in effect for all load modules regardless of any previous 
DDMP/NODUMP service command. This will allow the option to oe reset 
without having to cancel each previous command. Providing one or more 
load module names will set (or reset) the option for only those modules 
specified on that command. Any previous DUMP/NODDHP service commands 
for other modules will not be modified and will remain in effect- 
Note: The options in effect at the time of the ABEND are the options 
that will be honored except that dumps for ste p AB ENDS are not 
suppress ed. It should also be noted that the user exit routine 
invoked in response to the STAEX statement in the SYSINIT input 
stream will receive control before the STAE option processing 
is initiated. Any request by that routine to retry or bypass 
STAE option processing will take precedence over the STAE IMP 
command option in effect. 

Upon abnormal termination of a subtask executing under the real-time 
job step task, one of the Special Real Time Operating System STAE exit 
routines (DPPSTAE) will gain control. This routine will then examine 
the STAE command options in effect at the time of the ABEND to determine 
whether or not a dump should be taken for this task. 

Upon termination of the real-time job step task, another Special Real 
Time Operating System STAE exit routine (DPPISTAE) will gain control. 
This routine will unfix any storage previously fixed by the DPPIPFIX 
routine and clear the external interrupt handler flags. If the job 
step terminating is a MASTER job, the corresponding SLAVE job is also 
terminated (USER ABEND code of 41). If the job step terminating is a 
SLAVE job, the corresponding MASTER job is located, and the MASTER 
job's two-partition flags are turned off. 

It is important to note that there are certain conditions in which the 
STAE routine is not given control when the real-time job step is 
terminated (e.g., an operator CANCEL command) and these cleanup 
functions cannot be executed. Therefore, the user must use care and 
terminate a real-time job step by a reply to the Input Message Processor 
of the form 

r xx,CANCEL[ , . .- ] 

If the SLAVE partition has terminated with a supervisor ABEND code of 
122, 13E, 222, 322, or 722, an IMP command of the form 

r XX, CANCEL, SLAVE 

will ensure that the two- partition flags in the MASTER partition will 
be reset even though the SLAVE partition job is no longer active. 



Dynamic Load Module Purge 

The Dynamic Load Module Purge Facility permits the system operator to 
cause a load module, which has been loaded in response to one or more 
PATCH requests, to be deleted from virtual memory. Thus, the user can 
redefine a load module in the library (JOBLIB, STEPLIB, or LINKLIB) 
and purge the in-memory copy, so that when the load module is next 
requested, the new copy will be fetched. The redefinition may entail 
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replacing the existing copy of the load module or adding a copy on a 
data set that is searched ahead of the one on which it was originally 
found. The redefinition can be done in. a background partition or in 
a backup Systein/370 which shares disks with the online System/370. 
Through the use of this facility, the new load aodule can be integrated 
into the online system without otherwise disturbing the job. 

This procedure is not necessary for modules that are link-edited as 
non-reentrant because they are fetched from the library for each 
execution. 'Those modules that are represented in a system BLDL list 
are not normally affected by this procedure since the disk address of 
those modules is resolved at system IPL time and cannot be re-resolved 
except by re- IPL. Those modules that are identified in a Resident 
Access Method (RAM) list are loaded at IPL time and as such are also 
not affected. This procedure affects only those modules that are 
invoked through a PATCH or PTIME service and not those which may be 
loaded, attached, linked, or XCTLed to outside of the PATCH interface- 
Dynamic Load Module Purge is invoked by a reply to the Special Real 
Time Operating System Input Message Processor. 



r XX, D LM P, [ SLAVE, ]time , modulename, modulename. . . 

IP (^fifinc^.c: thfi rt^nl V as a command to Durae fh(> ati 



DLMP defines the reply as a command to purge the modules specified. 
Up to 10 module names may be specified with one command. If SLAVE is 
specified, the purge operation is performed in the SLAVE partition; if 
it is omitted, it is performed in the MASTER (or only) partition. A 
time value may be specified on the command as a decimal integer between 
0 and 1200; if omitted, a default of 2 is used. This value defines 
the maximum number of seconds that the DLMP program will wait to allow 
other tasks to complete execution of the specified load modules. 
Therefore, this value plus the necessary time for all DELETE operations 
is also the time that all other tasks with a request for one of the 
specified modules may have to wait before they are permitted to use 
their module. 



In response to the request, the Dynamic Load Module Purge program 
DPPTDLMP searches the TCB extensions for the Special Real Time Operating 
System tasks that have requests for, or are currently using, the 
specified load module (s) . If the task is not currently using one of 
the modules, it will not be permitted to resume using it until the 
purge operation has been completed. If a task is currently using the 
load module, a flag is set, and the current use is permitted to 
complete, but the task cannot process another WQE that requests a module 
in purge until the purge operation is completed. 

However, only those tasks are quiesced that have a WQE on top of the 
queue which requests a module that is in purge; every other execution 
continues undisturbed. DPPTDLMP waits the specified time for the using 
tasks to complete execution of the modules. If the time expires before 
all tasks are through, the operation is abandoned, and messages DPP021 
will specify the name of those modules that were not completed, plus 
message DPP022 will specify that the operation is abandoned. If all 
tasks complete using one or more of the specified modules in time, 
DPPTDLMP causes the module (s) to be deleted and message DPP023 will 
specify that the operation is completed- In either case, all tasks 
that had been quiesced are then allowed to resume normal operation. 



TIME MANAGEMENT 

The Special Real Time operating System provides time management 
facilities to meet the requirements of a real-time operating system. 
The Special Real Time Opcrcting System time management services fall 
into two major categories. First, the Special Real Time Operating 
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System time and date are maintained independently of the OS/VSl time 
and date. Second, the capability of issuing PATCHes on a cyclic time 
interval is provided through the PTIME macro call. Figure 2-7 is a 
block diagram of PTIME logic and control flow. 



DPPCTSVC 



DPPCTIMA 



DPPCTIME 




POST- 

DPPCPTIM 



PTIME 
Monitor 

Issues 
PATCH 



Figure 2-7. PTIME Logic and Control Flow 



A Special Real Time Operating System data base array, DPPCTIMA, contains 
the Special Real Time Operating System time and date in several formats 
as shown below: 



■^TIHED DSECT 
■f ** * 

+ * TIME ARRAY DSECT 

+ *** 

^-TIMEHS DC F»0' TOD IN 10 MIL UNITS IN HEXADECIMAL 

+TIMETOD DC F'0» TOD IN DECIMAL 10 MIL UNIIS-HH MMSSTH 

+TIMEJDAY DC F« 0« JULIAN DATE-OOYYDDDC 

+TIMEMDAY DC F'0« DAY OF MONTH D ATE- OMMDDYYC 

4-TlMEEBC DC CL10» EBCDIC D ATE-bDD/MMM/YY 

The Special Real Time Operating System time and date can be synchronized 
with an external time source or can be adjusted by manual inputs through 
customer- written interface programs. The Special Real Time Operating 
System time is updated at a periodic rate specified at the Special Real 
Time Operating System system build. A PTIME macro call will return 
the current Special Real Time Operating System time and the address of 
the Special Real Time Operating System time data base array. The 
address of the array can also be obtained from a pointer in the SCVT 
at label SCVTTIME or from a GETARBAY macro call for array name DPPCTIMA. 



The Special Real Time Operating System time management facilities 
provide the ability to specify PATCHes which will be issued by a time 
management task at the requested time intervals. The PATCH operands 
(e.g., time of the first PATCH, interval between PATCHes) are defined 
in the PTIME macro call. The PATCH may be issued only once at a 
specified time or repeated for a specified number of PATCHes. Also 
the PATCH may be issued repeatedly at a specified time interval for an 
indefinite period of time. The PTIME macro call can also be used to 
modify or delete a previously defined PTIME. 
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There are three functional areas of the Special Peal Time Operating 
System time management. 



• The PTIME macro and the resulting PTIHE SVC, DPPCTSVC, provide the 
user interface to time management. 

• The time update routine, DPPCTIME, operates as an OS/VS task and 
is responsible for maintaining the current Special Real Time 
Operating System time in the data base array. 

• The. DPPCPTIM monitor routine, which also operates as an OS/VS task, 
is responsible for issuing the PATCHes requested via the PTIHE 
macro call. 

The time management programs are described individually in the following 
section . 



PTIME Macro and PTIME SVC 

The PTIME macro provides the user with an interface to the Special Real 
Time Operating System time management services. 

PTIME can be used to cause a task to be given control at a given time, 
cyclically at a given interval, or cyclically at a given interval from 
time X to time y. 

There are four types of PTIME service requests: 

• RET This causes the system to return the current Special Real 
Time Operating System time in register 0 and the address of the 
Special Real Time Operating System time array in register 1. 

Note: since the time contained in the array is updated only at a 
periodic rate, the time returned as a result of a PTIME RET 
macro call will be aore exact than the array value, 

• ADD This causes the system to build a PTIME queue element (PTQE) 
which exists independently of the creating task. This control 
block contains all information required to issue a PATCH macro; 
that is, the PATCH parameters are built according to the "PATCH 
operands" specified on the PTIME macro and are contained in the 
PTQE. The PTQE also contains information necessary for issuing 
the PATCH at the specified time; and, if requested, repeatedly 
reissuing the PATCH at a given time interval until the specified 
number of PATCHes has been issued or until a specified stop time 
has been reached. A PTIME ID may be supplied by the or assigned 
by Special Real Time Operating System if omitted by the user. The 
ID will be returned to the user in register 1. 



Note: If the interval time is omitted or if the interval time is 
less than the SYSGEN time interval used for updating the 
Special Real Time Operating System time array, the SYSGENed 
time interval will be substituted for the interval time. 

• MOD — This causes an existing PTQE to be modified. Since the PTQE 
exists independently of the creating task, the PTQE is referred to 
by a combination of task name, entry point name, and/or ID value 
of the parameter referred to by the operands TASK=, TASKLOC=, EP-, 
EPLOC=, and/or ID=. Either task name or entry point name must be 
specified, but the remaining two are optional. An additional level 
of identification, the PTIME ID, can be used to uniquely identify 
a PTQE eventhough several PTQE's may exist with the same PATCH 
parameters. However, if only a task name or an entry point name 
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is specified on a PTIME HOD nacro call, all PTQEs with ^hat naiae 
are aodified regardless of the original entry point name or task 
naae, respectively- 

• DEL This causes an existing PTQE to be deleted. Since the PTQB 
exists independent of the creating task, the PTQE is referred to 
by a combination of task aaoe, entry point naae, and/or ID value 
of the parameters referred to by the operands TASK=, TASKLOC=, EP=, 
EPLOC=, and/or I0=. Either task naae or entry point na«e aust be 
specified, but the remaining tuo are optional. An additional level 
of identification, the PTIBE ID, can be used to uniquely identify 
a PTQE eventhough several PTQE*s aay exist with the saae PATCH 
paraaeters. However, if only a task naae or entry point name is 
specified on a PTIHE DEL aacro call, all PTQEs with that naae are 
deleted regardless of the original entry point naae or task naae, 
respectively. 

For exaaple, assuae that a given user prograa were to be executed 
froa a Special Real Tiae Operating Systea job step and assuae that 
the given prograa contained the following aacro calls: 



OHE PTIHE RET 

TWO PTIHE ADD,TASK=A,EP=X,ID=U, 

THREE PTIHE ADD,TASK=A ,EP=Y , ID=5, . . - 

FOUR PTIME ADD,TASK«B,BP=I,ID=5, 

PIfE PTIHE HOD,TASK«A,EP=I,ID=a, 

SIX PTIHE DEL,EP«X,..4 



nacro call "ONE" causes the current tiae and the address of the Special 
Real Tiae Operating Systea tiae array to be returned to the user. 

Hacro call "TWO" causes a PTQE to be built so that PATCHes could be 
issued for task A, entry point X with an ID of 4. 

Hacro call "THREE" causes a PTQE to be built so that PATCHes could be 
issued for task A, entry point Y, with an ID of 5. 

Nacro call "POUR" causes a PTQE built so that PATCHes could be issued 
for task B, entry point X, with an ID of 5. 

nacro call "FIVE" causes the PTQE built by macro call "TWO" to be 
aodified. 



Hacro call "SIX" causes the PTQEs built by aacro call "TWO" and "POOR" 
to be deleted. 

Note: If the PTQE is specified by a coabination task naae, entry point 
naae, and/or ID value cannot be located on a PTIHE HOD or DEL, 
no action is taken by the systea, and the user is notified of 
this condition by a return code of 8- That is, it had not been 
previously defined by a PTIHE ADD, it had been deleted through 
a PTIHE DEL, it had reached the specified STOP tiae, or it had 
issued the specified nuaber of PATCHes. 

The PTIHE aacro allows the user to specify a tiae to begin issuing 
PATCHes (START=), a tiae to cease issuing PATCHes {STOP=) , or a total 
nuaber of PATCHes to be issued (count*) , and a tiae interval between 
PATCHes (IHTBR?AL=). All tiae values are specified in the saae foraat. 
The tiae is specified explicitly by hours, ainutes, seconds, or any 
coabination of the three. The tiae value aust not exceed 2U hours. 



APPLICATION SERVICES 2-25 



For example, if a relative start time of three hours is required, the 
PTIflE aacro could be coded in any of the following three forms: 

PTIHE START=(3H) 

PTIWE START= (180n) .. 

PTIME START= (1H,60M, 3600S) , 

If a relative stop tiae of 1 hour, 3 minutes, 1 and 1/2 seconds is 
required, the PTIHB aacro could be coded as: 

PTIHE STOP= (1H,3M, 1. 5S) , . 

If four PATCHes are to be issued regardless of the start time, the 
PTINE macro could be coded as: 

PTIME CO0NT=4,.., 

In addition to explicitly coding the tiae fields within the PTIHE aacro, 
the required tiae values may be loaded in a register or contained in 
a fullword at the address specified. However, the time values aust be 
specified in binary hundredths of seconds to use either the register 
or address fora of the PTIHE aacro. 

For example, the following sequence of code 



LA 3,5 

PTIHE START=(A=ASTAST) ,CO0NT= (3 ) , 



ASTART DC F»500« 



would cause five PATCHes to be issued with a relative start tiae 
of five seconds. 

To allow greater flexibility in controlling the tiae of the PATCHes, 
three suboperands are peraitted with the START* and STOP= keyword 
paraaeters of the PTIHE aacro. 

• REL — This suboperand is used to indicate that the tiae value is 
relative to the current Special Real Tiae Operating Systea tiae. 
That is, the tiae value in the keyword paraaeter is added to the 
current Special Real Tiae Operating Systea tiae to determine the 
correct start or stop tiae. This is the default suboperand. 

• TOD This suboperand is used to indicate that the tiae value is 
tiae of day value. That is, the first PATCH will occur when the 
Special Real Tiae Operating Systea tiae is equal to the tiae of 
day specified in the reaainder of the operand. If this tiae value 
is less than the current Special Real Tiae operating Systea tiae, 
then the first PATCH will not be executed until the next day. 

• ADJ This suboperand is used to indicate that the tiae value is 
an adjusted time of day value,- That is, if the specified time 
value is less than the current special Real Time Operating systea 
tiae, then the tiae of the first PATCH is calculated by repeatedly 
adding the time value of the INTRVAL= operand to the specified time 
value until the sua is greater than the current Special Real Time 
Operating System time. This prevents the possibility of 
unintentionally specifying a TOD less than the current Special Real 
Time Operating Systea tiae and the first PATCH not occurring for 
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alBost 24 hours. If the specified tiae value is greater than the 
current Special Real Tiae Operating Syste* tise, the n processing 
ifould proceed as if the TOD suboperand had been coded. 

Assume that the current Special Real Time Operating System time is 
11:05, and the following PTIHE macro call was executed: 

ONE PTIHE ST ART= (TOD, 10H) ,STOP=( ADJ, 10H, 30H) ,INTHVAL= (1H) , . 

PTIHE macro call "ONE" would cause a PTQE to be built with a start time 
of 10:00- Since this is less than the current tine, a 24-bour value 
is added to the start time so that the actual start time is 10:00 of 
the following day. The specified stop time (10:30) would be adjusted 
to 11:30 (i.e., 10:30 plus the interval of 1 hour). Since the stop 
time would be less than the start time, a 24-hour value is added to 
the stop time so that the actual stop time would be 11:30 the following 
day. 

The remaining PTIHE operands are identical to the PATCH operands, and 
their functions are described in the PATCH macro documentation. Two 
restrictions should be noted. 

1. QPOS=DPATCH cannot be specified. LAST will be substituted. 

2. PBBE= Can be specified, but the PREEMAIN will not be executed 
until the PTIHE queue element (PTQE) generated by this PTIHE is 
deleted. If the PTQE is not repeating, this will be like a 
normal PATCH. 

note: In response to a PTIHE DEL request or a return code greater than 
8 on the resulting PATCH macro call, the FBEEHAIN will be 
executed when tiie PTQE is deleted, regardless of any outstanding 
work requests. This may result in abnormal termination of a 
program trying to reference the area that has been freed. 



HjBS CiPdate R out^-PC 

The time update routine executes under a high priority task and is in 
a continuous loop repeating at a rate specified during the special Real 
Time Operating System system generation. Each execution causes the 
time value in the data base to be updated. The value retrieved from 
the System/370 TOD clock is adjusted by a conversion factor so that 
the Special Real Time Operating System time can be maintained 
independently of the OS time routine. The time update routine detects 
any inconsistency between the TOD clock and the Special Real Time 
Operating System time. If an inconsistency is discovered, a new 
conversion factor is calculated to correct the Special Heal Time 
Operating System time. 

After the current Special Heal Time Operating System time has been 
calculated, the time update routine determines whether a PTQE requires 
servicing, and if so, the PTIHE monitor routine is notified. 



PTIHE Dse of the Clock Comparator 

The PTIHE time update routine normally controls its execution rate by 
issuing STIHER to delay for the specified amount of time. Optionally 
the PTIHE time update routine can be directed to use the optional clock 
comparator feature of the System/370, if 0S/VS1 is generated to not 
use this feature. This feature is selected by coding CLOCKCP=YES in 
the VS macro of the Special Real Time Operating System SYSGEN. PTIME 
usage of the clock comparator, if selected, is available to the first 
single partition real-time job step that enters the system or to the 
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first "!1&STER" partition to enter. Use of the clock comparator saves 
STIMER overhead. If other Special Real Tiae Operating Systea real-time 
jobs are also run at the same time, they will use the STIMER interface. 
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PTIME Monitor Routine 

The PTIME monitor routine is responsible for issuing PATCHes requested 
via a PTIME macro call. All active PTQEs with the time of the next 
PATCH less than the current time plus the SYSGENed update interval are 
serviced by issuing a PATCH. If the PTQE is repeating and the count 
of PATCHes has not been exceeded, the next PATCH time is calculated; 
otherwise, the PTIME request is terminated, and the PTQE is deleted. 



Tiffle Drift Corr ection 

Many real-time systems require highly accurate maintenance of time of 
day. The System/370 TOD clock is susceptible to a certain amount of 
drift. As a result, a user may wish to correct this drift by using a 
highly accurate external time source to correct for TOD clock drift. 
The time drift correction feature of the Special Real Time Operating 
System allows for correction of long term drift in the System/370 TOD 
clock. Time drift correction is optionally selected during the Special 
Real Time Operating System SYSGEN if support is required for an external 
time source. To include time drift correction in the Special Real Time 
Operating System, the TIMEEXT keyword on the VS macro of the Special 
Real Time Operating System SYSGEN must be coded to specify the external 
signal line (2-7) on which the time interrupt will occur. The external 
time source may then interrupt the Special Real Time Operating System 
at the given frequency and allow for correction. 

Time drift correction operates as a Special Real Time Operating System 
subtask with a module name DPPDRIFT- The feature operates by accepting 
external interrupts from the external source on a periodic basis from 
one per second to one per ten minutes- A period of one interrupt per 
minute is recommended. To create a time interval of other than one 
minute, the required value must be specified in the TIMERAT keyword of 
the VS macro during the Special Real Time Operating System SYSGEN. 

The external interrupts are assumed to be accurate. If the external 
time standard is not accurate, the TOD clock will appear to have 
excessive drift. An allowance is made for discrepancies caused by 
delay in the handling of the interrupt. This type of delay can occur 
if the interrupt arrives at a point in time when the CPD is disabled 
for external interrupts. 

Drift corrections are made by passing adjustment factors to the Special 
Real Time Operating System time routines which update the Special Real 
Time Operating System time conversion factor, not by altering the TOD 
clock. Time drift correction does not supply any initial times, it 
merely accounts for long term drift. The function of passing an 
adjustment factor and the functional relationship between time drift 
correction and the Special Real Time Operating System time management 
is illustrated in Figure 2-8 below. 
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SPECIAL REAL TIME OPERATING SYSTEM TIME MANAGEMENT 



DPPCALCF 



DPPCTIME 







Correction 
Factor 





DPPCUPCF 



L, 



DPPDRIFT 






CQcrfictiQn Factor 


PATCH 




EP = DPPCUPCF 





Figiire 2-8. Time Drift-Special Real Time Operating System Time 
Relationship 

The maximum correction made at one instant is 50 milliseconds; the 
minimum is 10 milliseconds. Errors of greater than 50 milliseconds 
are spread over succeeding corrections until the time error has been 
corrected. Small differences in which the TOD clock appears fast are 
not corrected immediately, as the difference may be due to processing 
or interrupt lockout time. These errors are averaged over many 
interrupts before the correction is made. Errors in which the TOD 
clock appears to be behind are always adjusted immediately. Interrupts 
indicating errors in excess of one second are ignored. Resetting of 
the Special Real Time Operating System time (PTIME) by an application 
prograa has no effect on drift accounting. The resetting of the TOD 
clock by a user program, however, will cause unpredictable results. A 
malfunction in the TOD clock that causes condition code settings of 2 
or 3 on an OS STCK instruction will cause the termination of time drift 
correction. 

Time drift correction supplies a user interface to allow a user's 
program to set current time. The first external signal time interrupt 
following the completion of initialization causes a LINK to DPPDRIFE. 
On entry to DPPDRIFE, general register 1 points to a doubleword 
containing the value of the TOD clock ^t the time of the external time 
interrupt. The module DPPDRIFE supplied by the Special Real Time 
Operating System is a dummy, and the user may replace with a module to 
set initial time. Using standard OS linkage conventions, DPPDHIPE can 
issue a PATCH to the Special Real Time Operating System time management 
to adjust the conversion factor (see Figure 2-8). The format of the 
data to be passed is described in the Special Real Time Operating System 
Program Logic Specification. 



Warning ; By whatever means the user version of DPPDRIFE determines 
the desired system time, the user must be aware that the 
time of its determination is some time later than the time 
stored at interrupt time. The amount of delay can be 
determined by reading the TOD clock and subtracting from it 
the value passed as a parameter (pointed to by register 1) . 
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Drift correction is available to the first single partition Special 
Real Time Operating System real-time job that enters the system or the 
first "MASTER" partition to enter. If more than one Special Real Time 
Operating System is run on the same 0S/VS1 system, time correction will 
be suppressed for the other Special Real Time Operating System systems. 
Thus for testing purposes, an application should be coded such that 
its DPPDRIFE routine does not have to be executed for the application 
to function. Time drift correction is never available to "SLAVE" 
partitions, as SLAVE partitions use their MASTER partitions time 
management tables. 



REAL TIME MESSAGE HANDLER 



The Special Real Time Operating System provides facilities for defining 
a series of messages by means of an offline utility program. These 
messages can later be modified and issued in real-time. All messages 
can be predefined and kept in a partitioned data set on a direct access 
storage device. This allows for easy modification of messages without 
making changes to functioning programs. It also allows for easy 
translation of all messages to other languages and avoids duplication 
of messages. The data set is created and updated by the offline utility 
program (DPPXUTIL) . It is used online only as input to the message 
writer. Although this data set is built by the offline utility, it is 
a normal partitioned data set and none of ttie data base data set 
restrictions apply to it. There are two components to the real-time 
message handler: offline processing and online message processing. 
This is illustrated in Figure 2-9. 
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Figure 2-9. Real Time Message Handler Components 



Offline P rocess ing 

The DEFMSG macro is used to define messages to the offline utility 
program that processes the macro and places the resultant skeleton 
message in the message data set. For further information on the offline 
utility, refer to the section entitled "Offline Utility Prograift". The 
DEFMSG macro defines a unigue message number, the routing code, action 
code, a date indicator, and the message text. 

The message number identifies a specific message and is the means by 
which online programs refer to that message. The message number has 
a range from 001-999. The Special Real Time Operating System messages 
fall within the range of 001-099 and 800-899- The user should not 
assign message numbers in these ranges. Related PRPQs should restrict 
their messages to a defined range. This is by convention only, and no 
restrictions are placed on the user's message numbers. 

The routing code (ROUTE=) is used to specify the output device to which 
the message is to be written. At the Special Real Time Operating System 
SYSGEN time, routing codes are established to identify the output device 
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The routing code has a range of 1-255. It can also identify a user 
program as a device, in which case the message is passed to the program 
as a PATCH parameter. A routing code must be specified with the DEFMSG 
macro. A routing code of 255 results in a no-operation (255 goes to 
no output device) . 

The action code {ACT=) identifies the type of action that the message 
reguires. ACT=I identifies the message as being informational only. 
ACT=A means that some action is required. ACT=D requires a decision 
to be made. These codes cause no action within the message output 
process but are intended for user information. 

The date indicator (DATE=) is the date that the message was issued from 
an online program. The date can be included (DATE=yES) or excluded 
(DATE=NO) . DATE=NO is the default. 

The message text (TEXT=) contains the text of the message to be written 
or passed to a PATCHed program. Hithin the text, there can be variable 
data. The variable data will be inserted when the message is issued 
online. Variables are specified to appear in the message by coding, 
in the message definition, information in the following format: 

#cfs# 

where: # (pound sign) is a delimiter character and must appear before 
and after the other specifications- No blanks are allowed 
between them. 

c defines the number of characters to be occupied by this 
variable in the output message. 

f defines the type of data conversion to be performed on the 
data being output. 

s specifies the position of this variable in the variable list 
that is passed by the calling program when the message is 
selected for output. 

The following are examples of the use of the DEFMSG macro. 

EXAMPLE 1: DEFMSG 307 ,RODTE=10, ACT=I, DATE=YES,TEXT=' THIS MESSAGE HAS 
NO VARIABLES' 

This defines message 307 as being informational; a routing code of 10, 
and the time and date which are to be inserted when the message is to 
be written. 

EXAMPLE 2: DEFMSG 2 , HO0TE=2 50 , ACT=D , D ATE= NO,TEXT= • PEOGR AM #8C1» 
HAS TERMINATED. SHOULD PROGRAM #8C2# CONTINUE?' 

This defines message 2 which has a routing code of 250. The date will 
not be formatted in the message, and the text contains two character 
variables . 

EXAMPLE 3: DEFMSG 5 0, ROUTE= 1 , ACT= D, TEXT=» MSG #3C3# HAS FIVE VARIABLES: 
#2F1#, #1H2#, #6B4#, #5X5#» 

Message 50 will require a decision, has a routing code of 1, will not 
print the date, and has five variables: 

1. #2F1# is the first variable with a length of 2 characters and 
integer format, and the user will provide a fullword for 
conversion . 
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2. #1H2# is the second variable with a length of 1 character, 
integer format, and the user will provide a halfword for 
conversion. 

3. #3C3# is the third variable with a length of three characters, 
and the user will provide 3 EBCDIC characters to be inserted. 

4. #6B4# is the fourth variable with a length of 6 characters, 
binary format, and the user will provide one byte for conversion 
(the six low order bits of the byte will be converted) . 

5. #5X5# is the fifth variable with a length of 5 characters, 
hexadecimal format. The user will provide 3 bytes of data for 
conversion (the five low-order hexadecimal digits will be 
converted) . 



Online Pr oces sing 

Messages are retrieved, formatted, and written during online processing 
through the MESSAGE macro. With the MESSAGE macro, options selected 
by the DEFMSG macro can be overridden, or omitted from the MESSAGE 
macro, and the DEFMSG options taken. The APEA= operand will indicate 
that the message is to be returned to the user specified area. The 
area should be defined at least to the maximum length of the message 
plus two bytes. The length of the message is put into the first two 
bytes of the virtual storage specified by AREA= and the formatted text 
in the remaining bytes. 

The maximum message length that can be moved is 255 characters. 

If the message contains variables, the user passes the data to be 
inserted in the message (VAR=) - The data is inserted in the order 
presented into the variables fields defined by the DEFMSG macro (see 
examples below) . 

In online processing, a message can be output to several devices by 
two methods. The MESSAGE macro allows up to 8 routing codes to be 
specified and the HSGRC macro of the Special Real Time Operating System 
SYSGEN can be included, for a given routing code, several times, each 
time specifying a different device- 

If a message is issued to a routing code that does not exist, no attempt 
is made to output the message, and a return code of 12 is returned to 
the user. When a message is issued to multiple devices, and one of 
the devices is out-of -ser vice , an attempt will be made to issue the 
iressage to the backup (alternate) device defined during SYSGEN, The 
out-of-service route code does not affect the other route codes. The 
message will still be output to these devices. 

The format of the message is an identifier, time, and date (if 
requested) , and text. The identifier is; 



DPPnnna 



where: 



nnn is message number 
a is the action code 



The time and date 



are represented by: 



HH:MM:SS.t 



DD/MMM/YY 



where: 



HH is hour 
MM is minutes 
SS is seconds 
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t is tenths of seconds 
MMM is month 
DD is day 
YY is year 

The message will be truncated to conform to the line length of the 
device selected by the routing code. 

When a message is routed to a user program, the PATCH parameters and 
the message will be in the following format. 



GPRl 



Register 1 
XCVT 
RESOURCE 



PATCH 
PROBL 



0 


2 


3 4 




LGTH 




ID 




A Formatted 
T Message 


0 2 



Length - Length of PROBL 

Lgth of Message - Length of Message 

, i - Address 

ID - PATCH ID 



Lgth 
of 

Message 



Formatted 
Message 



Note: All messages issued prior to the processing of a RESTART card 

and during initialization will be written to the system console. 
After the RESTART card is processed or if there was no RESTART 
card, the messages will be routed to their respective routing 
code devices. 

The following examples of the MESSAGE macro show the resulting messages 
for the previously defined DEFMSG macro. 

EXAMPLE 1: MESSAGE 3 07 ,ROOTE= ( 1 , 2, 3) , ACrr=A, AREA=MSG. In this example, 
message 307 will be routed to the devices identified by routing codes 
1, 2, and 3. The routing code on the MESSAGE macro overrides the RO0TE= 
from the DEFMSG macro. The formatted message will be returned to the 
user area labeled MSG. The resultant message will appear as follows: 

DPP307A 14:37:21:92 07/JAN/73 THIS MESSAGE HAS NO VARIABLES 

EXAMPLE 2: MESSAGE 2 , V AR= ( (7) , (8 ) ) - In this example, message 2 will 
be routed to the device or program for routing code 250. The date will 
not be printed. The message will reguire a decision. The registers 
(7 and 8) point to areas in virtual storage from which eight characters 
will be moved into the message variables before the message is written. 
Assuming that register 7 points to the eight characters TIMECALL, and 
register 8 points to the eight characters CORRFACT, the resultant 
message would appear as follows: 

DPP002D 12:22:20:21 PROGRAM TIMECALL HAS TERMINATED. 
SHOULD PROGRAM CORRFACT CONTINUE? 

EXAMPLE 3: MESSAGE 5 0, ROUTE= (2 1 , 1) , ACT=I , V AR = (A , B , C, D , E) . In this 
example, message 50 will be routed to the devices or programs specified 
by 21 and 1. The message consists of information, overriding the DEFMSG 
action A. The date will print as YES on the default. Assuming the 
following pointers: 
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A = fullword integer = DC F'320« 

B = halfword integer = DC H'9' 

C = character DC C'004' 

D = binary integer DC B'011011' 

E = hexadecimal DC X'CAa20' 

Th3 resultant message would be: 

DPP050I 14:39:20:07 07/FEB/71 MSG 004 HAS FIVE VARIABLES: 
320,09,01101 1, CA420. 



Message Routing Code sta tus C hang e Fa cility 



The Message Routing Code status Change Facility provides a service 
which allows the user to place a routing code in or out of service. 
The facility will also provide upon request the status of one or ail 
of the routing codes in the Special Real Time Operating System message 
handler. 

The facility is activated by an Input Message Processing (IMP) command. 

The format of the command is: 

MSGRC, )rc J IN [ 

0 I OUT r[,altrc] 
STATUS j 

statallI 

MSGRC Informs the IMP routine that this reply is for the 

Message Routing Code Status Change Facility. 

rc Routing code. 

0 This parameter is 0 if STATALL is specified. 

IN Place rc in service. 

OUT Place rc out of service- 

STATUS Display the status, via a system message, of the 

specified routing code (rc) . 

STATALL Display the status, via a system message, of all the 

routing codes in the system. 

altrc The routing code to which messages are directed should 

the primary routing code be out of service or the output 

operation fail. This parameter is recognized only if 
IN or OUT is specified. 



REPORT DATA OUTPUT FACILITY 

A facility is provided to transfer report data which is ultimately 
destined to be printed, from one or more working data sets to a QSAM 
supported output data set. 

The Report Data Output facility will write the data as it is generated 
to working data sets (QSAM data set on any QSAM device). Subsequently, 
the data may be transfered to a print device. The data could be 
collected from several working data sets by the report data output 
facility and written to another data set to be printed by a job step 
in another partition or another computer which shares direct access 
(DA) devices with the online computer^ 
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Figure 2-10. Report Data Output Facility Overview 

All input and output data sets used by the Report Data Output Facility 
must be BSAM data sets. The maximum record length must not be greater 
than 255. For a unit record device the BLKSIZE and LRECL must not 
exceed the maximum for that device. The Report Data Output Facility 
is invoked through IMP commands. 



— Il 

NEW (J .OUTPUT DDNAME, INPUT DDNAME, 
T DE 



h ADD 

REPORT,[SLAVE,] 

[input DDNAME,.. .^.INPuf DDNAME ] 
REPORT 

Informs the input message processing routine that this reply is for 
the Report Data Output Facility. 

SLAVE 

Indicates the PATCHed routine is to run in the SLAVE partition. 
NEW 

Report Data Output Facility starts writing data at the beginning of 
the output data set. 

ADD 

Report Data Output Facility adds all data at the end of the output 
data set. 

OUTPUT DDNAME 

A DD name which points to a QSAM data set to be used as the output 
data set. The BLKSIZE of the data set must be equal to or greater 
than the maximum BLKSIZE of the input data sets. 

INPUT DDNAME 

A DD name which points to a QSAM data set to be used as an input data 
set. A maximum of 1 0 input DD names may be specified. 
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INPUT MESSAGE PROCESSING 

The Special Real Time Operating System provides a facility to allow 
for operator--Special Real Time Operating System communication or for 
the operator to communicate with a subsystem. This facility is the 
Input Message Processor (IMP). The Special Real Time Operating System, 
during initialization, issues a MTOR and leaves the reply outstanding. 
At a later time, the operator may reply with a predefined IMP command. 
This IMP command is defined at SYSGEN by the IMP macro and also defines 
the action the Special Real Time Operating System is to take upon 
receiving the IMP code. The following example shows the seguence of 
events and alternate methods of invoking Input Message Processor. 



OPERATOR 




INPUT MESSAGE 


REPLY TO 




WTOR ROUTINE 




WTOR 




DPPXIMPW 



OR 



PATCH CARD 
IN INITIALIZATION 
INPUT STREAM 



OR 



PATCH FROM 
A USER 
PROGRAM 



Input Message Processing will accept IMP commands in the following 
format: "code, parami , param2, para mn" where code is the command word 
defined during SYSGEN by the IMP macro. Param corresponds to the 
parameters defined by the IMP macro. Any parameters may be omitted by 
entering double commas (null parameters). The command will be compared 
with entries in a table (an array in the data base). This table 
contains valid IMP commands, the names of the task and load module 
which process the command (the program to be PATCHed) , PATCH ID, and 
parameter conversion codes. If the IMP command is valid. Input Message 
Processing will patch the appropriate task with the specified input 
parameters. 

New commands can be added to the table through SYSGEN. Input Message 
Processing will accept commands from several different sources (as a 
reply to a WTOR, through a PATCH macro and initialization PATCH Input 
Cards). The different ways of entering IMP commands are described 
below. The keyword SLAVE in all cases is optional; and if omitted, 
should not have the comma included to represent its absence. 

• Input Message Processing will issue the following WTOR: * 

Input Message Processing Awaiting Reply In response to this 
WTOR, the operator can issue an IMP command. There will always be 
an outstanding WTOR in the system. In response to an IMP command. 
Input Message Processing will issue the following message (WTO) - 

IMP COMMAND RECEIVED. 

The IMP commands are in the following formal^: 

r xx,command , SLA VE , param 1 , param2 , . , - ,paramn 



INPUT MESSAGE 
PROCESSING 
ROUTINE 
DPPXIMPP 



A PREDEFINED 
SRTOS OR 
SUBSYSTEM 
ROUTINE 
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where r xx, is the format required by OS/VS- 

• IMP commands issued through initialization PATCH input cards must 
be in the following format; 

PI PATCH EP=DPPXIMPP,ID=0 

PAFAM= (C •command, SLAVE, par ami, para b2,. ,paramn 

EP=DPPXIWPP The entry point of the input message processing 

routine. No TASK= parameter is specified because 
the task must be dependent. 

ID=0 The ID must be 0- 

PARAM= (C'imp command*) is the IMP command to be processed. 

SLAVE The command is to be processed in the SLAVE 

partition. 

• IMP commands issued through a PATCH macro must be in the folloving 
format: 



P2 

ADDR 
IMPCODE 
where: 

ID = 1 
ADDR 



IMPCODE 



L r,ADDR 

PATCH EP=DPPXIMPP, ID=1 ,PARAM= ( (r) ) 

DC AL1 (LGTH) , AL3 (IMPCODE) 

DC C CO D8^, SLAVE, par ami , para m2 .. ,paramn 



The ID mast be 1 when entered through PATCH macro. 

This is a 4- byte area. The first byte contains the 
length of the IMP command and the next three bytes 
contain the address of the IMP command. 

Register 2-12 

The IMP command. 



The following example shows the parameters as they would appear when 
the task which is patched as a result of the IMP command gains control- 
If no parameters are passed, there will be no parameter pointer. A 
null parameter results in a zero address being passed for the parameter 
address. 
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t 


XCVT 


t 


RESOURCE TBL 


t 


PARAMETERS 



PROBL 



0 




2 


3 


LENGTH 


UNUSED 


ID 


LL 


t FARM 




PARAMETER 



T = The address of a parameter. 
LENGTH = Length of PROBL plus FARMS. 
ID = ID specified during SYSGEN. 

LL = Length of this parameter. 

FARM = ADDRESS of parameter. 

Note: The first LL and FARM parameters may contain zeros if only the 
last parameters of a multiparameter IMP code are specified, 
example: 



'code, , , param3 , param4*. 

When only the first parameters of a multi- parameter IMP code 
are specified, the last parameters defined during SYSGEN by IMF 
macro will be ignored. A comma followed by a comma with no 
intervening character constitutes a null parameter. 



EXAMPLE 1: This example shows an IMP command being defined: 

SYMBOL IMP C0DE=EXAMPLE1,TASK=DPPTEST, 
LM=DPFTEST,TD=0, 
PARAH= (CIO ,FU,X3) 

In this example, an IMP command is defined with a command word of 
EXAMPLE1. DFFTEST will accept three parameters: 

1. a character parameter of length 10- 

2. a full word parameter of length H. 

3- a hexadecimal parameter of length 3- 

For more details on defining IMP commands see the section on SYSGEN 
macros (IMP macro) . 
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EXAMPLE 2: In this example, the IMP command defined in EXAMPLE 1 will 
be entered through the system console as a reply to the WTOR "INPUT 
MESSAGE PROCESSING WAITING ON REPLY". 

r XX ,« EXAMPLE1 , SLAVE ^StART' 

SLAVE parameter says DPPTEST is to execute in the SLAVE partition. 
When DPPTEST is entered, the parameters will be in the following 
format: 



b IS A BLANK 




EXAMPLE 3: In this example, the IMP command defined in EXAMPLE 1 will 
be entered through the initialization input stream, 

PATCH EP=DPPXIMPP,ID=0, 

PARAM= (C'EXAMPLEI , START, ,12' ) 

When DPPTEST is entered, the parameters will be in the following format: 




ft IS A BLANK 
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EXAMPLE U: In this example, the IMP command defined in EXAMPLE 1 will 
be entered by a PATCH macro. 

The IMP code follows: 

L r,ADDF 

PI PATCH EP=DPPXIMPP,ID=1 ,PAEAM= ( (r) ) 

ADDR DC AL1 (21 ) , AL3 (IMPCODE) 
IMPCODE DC C'EXAMPLEI, START, 708, 12» 

When DPPTEST is entered, the parameters will be in the following format: 




b IS A BLANK 
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DATA BASE MANAGEMENT 

The Special Real Time Operating System data base is designed to fulfill 
the needs of data storage and access of a realtime operating system. 
The Special Real Time Operating System data base subroutines provide 
the user with an interface to the information contained in the data 
base. Through the use of these subroutines, data may be retrieved from 
or replaced in the data base. In addition, sections of the data base 
may be copied to a direct access device to provide an historical log. 

The data base consists of data items ifhich are logically grouped into 
arrays. These arrays may also contain one or more blocks of related 
information. Each block is identical in size and shape to every other 
block within that array. For example, assume that the temperature and 
volume are to be monitored for three separate storage tanks. The two 
items (temperature and volume) can be grouped into one block. Three 
blocks (one for each storage tank) can be grouped into one array. This 
array can then be logged on a cyclic time interval to provide a history 
of the contents of the storage tanks as shown below. 



Block I 
StDrage Tank I 

Block 2 
Storage Tank 2 

Block 3 
Storage Tank 3 



ilcni A - Temperature 
Item B - Volume 



Item A - Temperature 
Item B - Volume 



Item A - Temperature 
Item B - Volume 



The Special Real Time Operating System arrays can either reside in VS 
or on a DA device. Duplicate data set support will be provided for 
all data base data sets (i.e., data sets containing DA resident arrays). 
However, it is the user's responsibility to ensure that the data base 
data sets do indeed meet the requirements for duplicate data set 
support, to create the required backup data set (s) , and to identify 
these data sets through the normal duplicate data set input stream 
(refer to the section entitled "Duplicate Data Set Support" for a 
detailed description of duplicate data set) . VS resident arrays may 
either be blocked or nonb locked arrays and are eligible to be logged. 
All DA resident arrays must be blocked and cannot be logged. An array 
that contains a copy (or copies) of a loggable VS resident array is 
called a log array. All log arrays must be DA resident. All arrays 
must be defined by the offline data base utility which is discussed in 
detail in the section entitled "Offline Utility Programs." 

The data base utility builds two data sets: (1) a data base 
initialization data set containing all the information necessary for 
the online data base initialization routine to construct the required 
control blocks, and (2) a composite items data set containing all the 
information necessary for the online data base subroutine to locate a 
particular item or items. 

During a normal start, i.e., when the job is initially started through 
standard OS/VSI Job Control statements with the EXEC card specifying 
PGM=DPPINIT, the data base initialization program will read in the 
initial data for all VS resident arrays that specified "INIT=YES" on 
the ARRAY macro in the offline utility phase. Those VS arrays for 
which "INIT=YES" was not specified have VS storage space allocated, 
but no data is moved into the space. 

During a refresh start, i.e., when the job is reinitialized from a 
restart data set, or during a normal start when the SYSINIT input stream 
does not contain a "DBREF NO" control statement, the data base 
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initialization program will refresh all VS resident arrays that 
specified "REINIT=YES" and that requested logging in the offline utility 
phase with the last logged copy of that array. The log arrays are 
initialized to resume logging with the last logged copy of each loggable 
VS resident array. 

Note that VS resident arrays are arranged in virtual storage by the 
USE code specified during offline utility processing. Arrays with 
similar USE codes are grouped together in virtual storage. This is 
intended to optimize the use of real storage by improving the 
probability that the hi.gh usage arrays will remain in real storage. 
Grouping high usage arrays will cause them to be distributed in a 
smaller number of pages to reduce the number of page faults. 



Data Base Access Routine 

Access to the data base is achieved through a set of six macros: 
GETITEM, PUTITEM, GETBLOCK, PUTBLOCK, GETAREAY, and PUTARRAY as shown 
in the following example. 



User 
Program 



GETITEM 
PUTITEM 



GETBLOCK 
PUTBLOCK 



GETARRAY 
PUTARRAY 



Data Base 
Subroutines 



DPPDITEM 



DPPDBLOK 



DPPDARAY 



Composition 
Items 
Data Set 



Data Base 



VS 
Resident 
Array 



DA 
Array 



VS 
Resident 
Blocked 
Array 



VS 
Resident 
Non Blocked 
Array 



GETITEM 

The GETITEM macro can be used to retrieve certain information from one 
or more items in the data base. This information is stored in the 
address indicated by the DATA= keyword parameter. The user may request 
that the address within the data base of the item (s) and length of the 
item(s) be retrieved (TYPE=ADDP) or that the data contained in each 
item be returned (TYPE=DATA) . TYPE=DATA and TYPE=ADDR are valid for 
direct access resident arrays. For blocked arrays, the user must 
specify the number assigned to the data block which contains the item 
(BLKN=number) . The item or items for which information is to be 
retrieved is indicated with the NAME=, NAHELST=, or ADDRLST= keyword 
parameter. The NAME= keyword parameter is an 8-character name of a 
single item for which information is to be retrieved. The NAMELST= 
keyword parameter specifies the address of a list of 8-character item 
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names for which information is to be retrieved. The ADDRLST= keyword 
parameter specifies the address of a list of data base item addresses 
which were returned from a previous execution of this macro with NANE= 
or NAMELST= specified and TyPE=ADDF. The PROTECT^: keyword parameter 
allows the user the option (PROTECT^ YES) of preventing other programs 
from modifying the data base during the execution of this GETITEM- If 
PPOTECT=BISK is specified, the information will be moved without regard 
to other programs which may be storing into the data base. 

The following examples indicate how the GETITEM macro may be used to 
retrieve information. 





GETITEM 


NAMELST=A, 


TYPE=ADDR,DATA=B 




GETITEM 


ADDRLST=B, 


DATA =C,TYPE=DATA,PROTECT= YES. 


A 


DC 


CL8« ITEM1» 




A1 


DC 


CL8«ITEM2« 






DC 


X» FP' 




B 


DC 


A(0) 




B1 


DC 


A(0) 






DC 


ax 'FF' 




C 


DC 


CL16» • 




CI 


DC 


C132' » 





The first GETITEM will move the length and address of items ITEM1 and 
ITEM2 into the data fields B and B1 , respectively. The second GETITEM 
will move the data associated with the items whose addresses are 
contained in the address list fields, B and B1, into the data fields, 
C and CI, respectively. Therefore, data associated with ITEM1 will 
have been moved into C, and data associated with ITEM2 will have been 
moved into cl . 



POTITEM 

The PUTITEM can be used to store data into one or more items of the 
data base. This data is moved from the address indicated by the "DATA=" 
keyword parameter. For blocked arrays, the user must specify the number 
assigned to the data block which contains the item (BLOCK NO=n umber) . 
The item or items for which data is to be stored is indicated with the 
NAME=, NAMELST=, or ADDRLST= keyword parameter. The NAME= keyword 
parameter is an 8-character name of a single item for which data is to 
be stored. The NAMELST= keyword parameter specifies the address of a 
list of 8-character item names for which data is to be stored. The 
ADDRLST= keyword parameter specifies the address of a list of data base 
item addresses as returned from a previous execution of a GETITEM macro 
with a NAME= or NAMELST* specified and a TYPE=ADDR- 



GETBLOCK 

The GETBLOCK macro can be used to retrieve one or more data blocks from 
one or more blocked arrays. The arrays may be either VS or DA resident 
arrays. The NAME= and NAMELST= keyword parameters are used to indicate 
the 8-character name or names of the arrays from which one or more 
blocks of data are to be retrieved. The NUMBER and NUMBLST= keyword 
parameters are used to indicate the two-byte number or numbers assigned 
to a numbered array or arrays from which one or more blocks of data 
are to be retrieved. The DATALST= keyword parameter specifies the 
address of a list of block numbers and associated memory addresses 
where the data blocks are to be written. Each entry in the list will 
contain a byte flag field, a 3-byte area address, and a 2-byte block 
number. A flag byte of X'UO' indicates the last entry to be processed 
for a particular entry in the name list or number list. 



Description and Operation Manual 



The PPOTECT= keyword parameter allows the user the option (PROTECT=YES) 
of preventing other programs from modifying the data base during the 
execution of this GETBLOCK. For DA resident arrays, a PROTECT=YES 
request will reserve the data set containing the specified array. For 
VS resident arrays, the VS resident data base is reserved. If 
PROTECT=RISK is specified, the information will be moved without regard 
to other programs which may be storing into the data base. 

For an example of the use of the GETBLOCK macro, assume that array 
FIRST is a VS resident blocked array and array SECOND is a DA resident 
array. For this example, each array is assumed to be composed of three 
UO-byte blocks- If the following GETBLOCK macro were to be executed, 
blocks 1 and 3 of the array FIRST would be moved into the DATA1 and 
DATA2, respectively. 

The entire array SECOND (blocks 1,2, and 3) would be read into DATA3, 
DATA4, and DATA5, respectively. 





GETBLOCK 


NAMELST=A, DATALST=B,. 


B 


EQU 


* 






DC 


X' 0« , AL3 (DATA1) , 


H» V 




DC 


X» aO» , AL3(DATA2) 


,H«3« 




DC 


X« 00» , AL 3 (DATA 3) 


,H'1« 




DC 


X' 0» , AL3 (DATA4) , 


H« 2» 




DC 


X' aO« , AL3(DATA5) 


,H»3« 


A 


EQU 


* 






DC 


CLS'FIRST* 






DC 


CL 8 • SECOND' 






DC 


X»FF« 




DATA1 


DC 


10F« 0« 




DATA2 


DC 


lOF'O' 




DATA3 


DC 


10F»0« 




DATA4 


DC 


10F» 0' 




DATA5 


DC 


IGF' 0' 





DATA1 
DATA2 
DATA3 
DATA4 
DATA 5 



'FIRSTV 
'FIRST3' 



'SECr 
■SEC2' 



•SEC3' 



VS Data Base 



Block 1 



Block 2 



Block 3 



Array 
FIRST 



DA Data Base 



Block 1 
Block 2 
Block 3 



Array 
SECOND 
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PUTBLOCK 



The PUTBLOCK macro can be used to move data from one or more user 
specified virtual storage locations into one or more blocks of one or 
more blocked arrays. The arrays may be either VS or DA reoident arrays- 
The NAME= and NAMELST= keyword parameters are used to indicate the 
8-character name or names of the arrays into which one or more blocks 
of data is to be written. 

The NUMBER= and NUMBLST= keyword parameters are used to indicate the 
two-byte numbers assigned to a numbered array (s) into which one or more 
blocks of data are to be written. The DATALST= keyword parameter 
specifies the address of a list of block numbers and associated storage 
addresses from which data blocks are to be written* 

Other routines executing data base requests with a PROTECT=YES option 
will be prevented from accessing the VS resident data base (or DA data 
set) during the execution of a PUTBLOCK request. 



GETAPRAY 

The GETARRAY macro can be used to retrieve data which is stored in VS 
resident array(s), to retrieve the address of and certain information 
about VS or DA resident array (s) , or to determine specific information 
about all items defined as part of VS or DA resident array(s). Hhich 
type of data is to be retrieved is specified by the TYPE parameter. 
The array for which data is to be retrieved is identified through the 
NAME, NAMELST, NUMBER, or NUMBLST keyword operands. The NAME= parameter 
specifies the 8-character name of the array as defined through the 
offline utility data base definition. The NDMBER= parameter specifies 
the number (1-255) of the array. Associated with the NAME= or NDMBER= 
parameter, the DATA= parameter specifies the address to which the data 
is to be moved. 

The NAMELST= parameter specifies the address of a list of 8-character 
names of one or more arrays for which data is to be retrieved. The 
NUMBLIST= parameter specifies the address of a list of one or more 
halfwords which contain the numbers which identify the arrays for which 
data is to be retrieved. The area(s) into which data is to be moved 
when NAMELST or NUMBLST is specified are identified by the DATALST or 
FINDLST parameters. 

The data to be returned is specified by the TyPE= parameter. If 
TYPE=DATA is specified, the content of the entire array (s) is moved 
into the area specified by the DATA= or DATALST= parameters. If 
TYPE=SPEC is specified, the specification information (16 bytes) is 
returned for each item contained in the specified array (s) . This 
information contains, for each item, item name, length of the item, 
defined data type, displacement into the array of the first byte of 
the item and repetition factor (number of identical items defined by 
one ITEM definition statement). If TYPE=ADDR is specified, 8 or 10 
bytes of data are returned. This data contains a flag byte, the address 
of the array (if VS resident) , the number of blocks defined for the 
array, and the size of the array (if unblocked) or the size of each 
block. Optionally, the number of items defined for the specified 
array (s) may also be retrieved. 
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GETARRAY EXAMPLE 1: This example will retrieve the content of array 
ABC into the area specified by the symbol ABCAREA. It is assumed that 
array ABC is less than or equal to 100 bytes. 



GETARRAY 
ABCAREA DC XLIOO'O' 



NAME=ABC»DATA= ABCAREA, TYPE=DATA, . . . 



GETARRAY EXAMPLE 2: This example will retrieve the address and 
associated data for array number 1 into the area specified by symbol 
ADDR1 . 



GETARRAY 



NUMBER=1 ,DArA=ADDR1,TYPE=ADDR, . . . 



ADDR1 



DS 
DC 
DC 
DC 
DC 



OF 

XL1 ' 0 • 
AL3 (0) 
H'O' 
H' 0« 



Flag byte 
Array address 
Number of blocks 
Size of array or block 



GETARRAY EXAMPLE 3: This example will retrieve the addrsss data for 
each array specified in list 'ADRL'. Since the increment (the second 
subpar ameter) of the FINDLST is greater than 10, the number of items 
in the array will be returned also. This increment causes the returned 
addresses to be moved into storage locations separated by 12 bytes for 
each entry. 



GETARRAY 



NAnELST=ADDL,FINDLST=(FINDL,12 ) ,TYPE=ADDR 



ADRL 



FINDL 



DC 


CL8 ' 


A1 • 




DC 


CL8' 


A2' 




DC 


CL8' 


A3 • 




DC 


X» FF 


t 


Flag byte to terminate the name 


DS 


OF 






DC 


X« 0« 




Flag byte for array A1 


DC 


AL3« 


(0) • 


Address of array A1 


DC 


H«0' 




Number of blocks in array A1 


DC 


H» 0' 




Length of array or each block 


DC 


H«0» 




Number of items in array 1 


DC 


H' 0* 




Pad list to 12 bytes 


DC 


2XL12' 0« 


Space for 2 additional lists as 








arrays A2 and A3 


DC 


XL4» 


0* 


Space for list termination flag 
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GETARPAY EXAMPLE 4: This example will cause the data from the arrays 
for which the addresses had been previously retrieved (as in example 
3) to be retrieved. The data from the first array will be moved into 
area A1DATA; from the second array into area A2DATA, etc. It is assumed 
for this example that all three arrays are less than or equal to 100 
bytes. For this example, it is assumed that the example 3 macro has 
been successfully executed to establish valid data into the following 
fields. 

GETARRAY ADDRLST= (FINDL , 1 2) ,DATALST=D ATAL,T YPE=DATA , . . . 



DATAL 


DC 


A( AID, A2D, A3D) 


AID 


DC 


XL100«0» 




A2D 


DC 


XL100' 0* 




A3D 


DC 


XL100' 0* 




FINDL 


DS 


OF 






DC 


X«0» 


Flag byte 




DC 


AL3' 0' 


Addr. of array 




DC 


H • 0 • 


Number of blocks 




DC 


H' 0' 


Length of block or array 




DC 


H'O' 


Number of items 




DC 


H' 0» 


Unused 




DC 


2XL1 2 '0» 


Space for 2 repeats of above 




DC 


X' FF' 


List terminator flag 



PUT ARRAY 

The PUTARRAY macro is similar to the GETARRAY with the difference being 
that data is moved from the user's area to the VS resident data base. 
There is no TYPE= parameter on the POTARRAY macro, so when compared to 
the GETARRAY macro, execution is always as if TYPE=DATA were specified. 



Logging 

Data base logging is a Special Real Time Operating System option which 
may be selected at the Special Real Time Operating System SYSGEN time 
by the LOG macro. 

During the offline utility phase, the user specifies which VS resident 
arrays are to be logged. These are called loggable arrays. A DA 
resident array with the array name specified by the LOGNAME keyword 
parameter in the ARRAY macro is constructed for each array to be logged. 
This array is called a log array. The LOGDD keyword parameter specifies 
the name of a data definition statement which describes a BDAM data 
set where the log array is to reside. The LOGCOPY keyword parameter 
specifies the number of historical copies that can be contained in this 
log array. 

For example, the following ARRAY macro causes the offline utility 
routine to generate the following array structure. 

ARRAY NAME=VSARRAY,LOGNAHE=LOGASRAY, * 

LOGDD=DBLOG1,LOGCOPY=2,. .. * 
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Primary Array Locator Table 



VS Resident Arrays 



A(VS ARRAY) 



A(LOGARRAY) 



VSARRAY 



Loggable Array 
VSARRAY 




The first logging request for VSARRAY would cause the VS resident array 
to be copied into the space allocated for copy 1. The second logging 
request for VSARRAY would cause the VS resident array to be copied into 
the space allocated for copy 2- Since all the space allocated to the 
history files for VSARRAY has now been filled, the third logging request 
for VSARRAY would cause the VS resident array to be copied into the 
space allocated for copy 1 overlaying the data logged as a result of 
the first logging request. 

To prevent a loss of history data, the user may specify the name of a 
user-written load module to be given control when the last block of 
the logging array has been filled through the LOGWRAP keyword parameter 
of the ARRAY macro. This load module will be entered via a PATCH to 
a dependent task. It is that load module's responsibility to preserve 
a record of the contents of the logged array at that time, possibly by 
dumping the log array to a sequential data set by the execution of a 
DUMPLOG macro call. Tf no user program has been specified, the user 
will not be notified that wraparound has occurred. The LOGFREQ keyword 
parameter consists of a code from 0 to 3 specifying the frequency at 
which the VS resident array is to be logged. A code of 0 indicates 
that it is to be logged only on demand, i.e., only when the user program 
executes a PUTLOG macro call. Codes 1 to 3 are used in conjunction 
with system generation parameters to specify the log frequency. A code 
of 1 is the highest frequency and 3 is the lowest. The Special Real 
Time Operating System logging routines will issue a PUTLOG for all VS 
arrays that are to be logged on the specified log frequency. Three 
macro calls; PUTLOG, GETLOG, and DUMPLOG, provide the user interface 
with the log subroutines. 



PUTLOG 

The PUTLOG macro is used to copy the VS resident array to the proper 
copy of the log array. The NAME and NAMELST keyword parameters are 
used to specify the 8-character names of the VS resident array (s) from 
which data is to be logged. The NUMBER and NUMBLST keyword parameters 
are used to specify the 2-byte number (s) assigned to a numbered VS 
resident array(s) from which data is to be logged. 

The user may replace a previously logged copy of the VS resident array 
without interrupting the normal sequential logging process. To 
accomplish this, the user would retrieve a log copy from the log array 
by executing a GETLOG macro call. This would read the requested log 
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copy along with the log header into VS storage. The logheader contains 
the time this copy of VS resident array was logged and a pointer to 
its location in the log array. The user may then modify the data in 
this log copy and replace the log copy by executing a PUTLOG with the 
LOGHDR keyword parameter specifying the address of the previously read 
in logheader. The copy of the array that will replace the copy in the 
log array is assumed to immediately follow the specified logheader. 
If the logheader in the log array does not match the logheader indicated 
by the LOGHDR parameter, the logged copy will not be replaced. This 
will prevent the possibility of accidentally overlaying a newer log 
copy. The LOGHDR parameter is not valid with the NANELST and NUHBLST 
keyword parameters. 

The user also has the capability of updating selected blocks of the 
last logged copy in the log array for blocked VS resident arrays through 
the use of the POTLOG with BLKLIST option. The BLKLIST keyword 
parameter identifies the blocks in the VS resident array that are to 
be logged. Each entry in the list must contain at least a 1-byte flag 
field and a 2-byte block number. A flag byte of indicates the 

last entry to be processed for a particular entry in the name list or 
number list. The POTLOG when executed with the BLKLIST option will 
cause the log array block that corresponds to the specified VS resident 
arr.^y block to be updated in the last log copy of the log array. The 
entire log copy is not updated and repeating POTLOG macro calls with 
the BLKLIST parameter will update the same log copy. A PUTLOG without 
the BLKLIST parameter will cause the entire VS resident array to be 
logged to a new log copy. 

For example, assume that loggable array. A, consists of four logical 
blocks, and the associated log array, B, has been defined to contain 
three complete copies of loggable array A. Because of the physical 
block size of the data set that contains a log array, each copy of the 
loggable array may be placed in one or more blocks of the log array. 
Assume that each copy of loggable array A can be placed in two blocks 
of log array P. Therefore, the entire log array, B, would consist of 
six blocks (i.e., three copies and two blocks per copy). 



Array A 



BLOCK I 



BLOCK 2 







BLOCK 4 



LOG ARRAY B 



BLOCK I 



BLOCK 3 



BLOCK 4 



BLOCK 5 



BLOCK 6 



LOG COPY I 



_ LOG COPY 2 



LOG COPY 3 



The user might issue a PUTLOG to log an entire first copy of array A, 
and at sometime later issue a PUT BLOCK to update block 3 of the VS 
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resident array A followed by a POTLOG, with the BLKLIST option, using 
the same data list. The log block in the log array that contains the 
request loggable array block would be updated. That is, blocks 3 and 
t» from the loggable array A would be moved into block 2 of the Log 
Array B. 



GET LOG 

The GETLOG macro call can be used to retrieve copies of arrays that 
have been logged to the log array on the basis of time or by specifying 
a particular logheader* The NAME keyword parameter specifies the name 
of a VS resident array for which a logged copy is to be retrieved. The 
NUMBER keyword parameter specifies the number of a VS resident numbered 
array for which a logged copy is to be retrieved. The AREA keyword 
parameter specifies the address of the user allocated area of storage 
where the logged copy of the array is to be written upon retrieval from 
the log data set. This area must be large enough to contain the entire 
log copy plus the log header information. 

The TIME keyword parameter specifies the time and day to be used as a 
comparison value to establish a relative starting point to determine 
which copy of the array will be retrieved from the log data set- An 
attempt will be made to locate a copy of the array logged at the exact 
time specified. If a copy of the array with the exact time cannot be 
found, the first copy of the array logged after that time will be used. 

The LOGHDR keyword parameter specifies the address of an array 
logheader- Information in this logging header will establish a relative 
starting point to determine which copy of the array will be retrieved 
from the log data set. The logging header which was retrieved as part 
of a previous GETLOG macro call can be used to retrieve additional data 
by stepping either forward or backward in time^ TIME and LOGHDR are 
mutually exclusive- 

The STEP keyword parameter is used in conjunction with either the TIME 
or LOGHDR parameter to determine the copy of the VS resident array to 
be retrieved from the log array. The value specified in the STEP 
parameter is a signed number which may be either positive, negative, 
or zero- The absolute value of the number specified must be less than 
the number of log copies in the log array- The value indicates the 
number of copies prior to or after the log copy determined by either 
the TIME or LOGHDR parameter. 

If the TIME, LOGHDR, and STEP parameters are omitted, then the latest 
logged copy of the array will be retrieved. For example, assume that 
the log array LOG contains five log copies of VS resident array, ARRAY. 



Log Array - LOG 



Copy 6 


Copy 7 


Copy 3 


Copy 4 


Copy 5 


6:00 


7:00 


3:00 


4:00 


5:00 



t 

Next Log Copy 

This array had been logged hourly for 7 hours starting at 1:03. 
Therefore, copies 1 and 2 would have been overlaid by copies 6 and 7, 
respectively, because of the wraparound processing- The following 
macro calls would all result in retrieving the same log copy, copy 4- 

1. GETLOG TIME=T,STEP=1,--- 
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2. GETLOG TIME=X,STEP=-3,AREA=LH,.., 

3. GETLOG LOGHDH=LH, STEP=0 

T DC •2:30» — Actual value is in 10 millisecond units 
X DC '7:00' 

LH DC 'COPY «♦' — Actual logheader. 

Example 1 will find the first time logged after 2:30 and step 1 entry 
forward. Example 2 will find the first time logged after 7:00 and step 
backward 3 entries. Example 3 presumes that the logheader from 
example 2 exists in 'LH'; this example will retrieve the same data, 
since STEP=0. 



DUMPLOG 

The DOMPLOG macro call can be used to dump or unload the historical 
log copies of VS resident arrays from the log array to a user defined 
sequential data set. This sequential data set may then be accessed by 
user-written routines. 

Note: Duplicate data set support is not provided for the user-defined 
sequential data set used in DUMPLOG processing. 

The NAME and NAMELST keyword parameters specify the 8-character name(s) 
of the VS resident arrays for which the locf array (s) are to be duAped. 
The NUMBER or NUMBLST keyword parameters specify the 2-byte number (s) 
assigned to a numbered array (s) for which the log array (s) are to be 
dumped. 

The DUMPDD keyword parameter specifies the name of a data definition 
(DD) statement which describes a sequential data set to receive the 
dumped copies of the array from the log array. The USRDATA keyword 
parameter specifies the address of a 256-byte area of user data to be 
used as a dump header for each array on the sequential dump data set. 

The log copies to be dumped are indicated by the STARTIM and STOPTIM 
keyword parameters. The STARTIM parameter specifies the time and day 
to be used to determine the first log copy to be dumped. An attempt 
will be made to locate a copy of the array with the exact time; if it 
cannot be found, the first copy of the array logged after that time 
will be used as the first log copy to be dumped. If STARTIM is omitted, 
dumping will commence with the oldest logged copy of the array. 

The STOPTIM parameter specifies the time and day to be used to determine 
the last log copy to be dumped. An attempt will be made to locate a 
copy of thie array logged at the exact time specified. If a copy of 
the array with its exact time cannot be found, the log copies of the 
array will be dumped until the most recently logged copy has been dumped 
or until the first copy of the array logged after that time has been 
dumped. If this parameter is omitted, dumping will terminate when the 
most recently logged copy of the array has been dumped. 

Note that the DUMPLOG routine will insert a byte of 'FF' into the first 
byte of the logheader of. the last copy of each array dumped to the 
sequential data set. This is done to indicate the end of the dump of 
each array to the user delog routine. 



BSfej^ Base Eef resh F unct ioii 

The data base refresh function will allow the user to replace the 
current contents of one or more loggable VS arrays with the contents 
of the most recently logged copy(s) of the array(s). To invoke the 
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function, the requesting program must PATCH the refresh program 
DPPDOPDL. 



The PATCH request will consist of a list of arrays to be refreshed. 
If no list is specified, all refreshable arrays will be refreshed- A 
refreshable array is any array that was defined via the offline utility 
with the REINIT=YES parameter on the ARRAY macro. These modifications 
do not supersede the option of placing a DBREF card in the 
initialization stream if the data base is to be refreshed during 
initialization. 

The PATCH macro format is as follows: 

Symbol PATCH TASK=t askname, EP=DPPDOPDL, 



LIST 





PARAn= (LIST) , 

the user may 


DS 


OH 


DC 


CL8* name* 


DC 


CL8* name ' 


DC 


H' number, ' XL6» 0' 


DC 


H' number XL6» 0« 


DC 


X» FF 


or 




LA 


R,LIST 


PATCH 


TASK=taskname, EP=: 



Symbol 

PARAM= ((R) ) 

R is any register (2-12) 

or 

Symbol PATCH TASK=taskname, EP=DPPDUPDL 

TASK= May be omitted to cause the program to execute as a dependent 

task or may specify any valid task name* 

LIST Is the passed parameter list of the data base arrays to 

refresh. The list consists of 8-byte entries terminated by 
a byte of X'FF'. Each entry will consist of an 8-character 
array name or a half-word array number in 2 bytes followed 
by 6 bytes of zeros. 



DATA RECORDING AND PLAYBACK 

Data recording and playback provide a service which allows user programs 
to write data to a sequential data set and to retrieve that data at a 
later time. Both are standard Special Real Time Operating System 
services (not SYSGSN options) . Data recording collects the data from 
several user programs, adds to it appropriate control information and 
user-supplied identifications, and writes the data to a sequential tape 
or disk data set. Data recording can be supressed or enabled through 
operator command (see "Input Message Processing") . Recorded data can 
later be selectively read back (based on time and ID) and passed to a 
user program or to the Special Real Time Operating System hexadecimal 
data print (hex dump) routine if no user program is supplied. The data 
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may be printed, used to drive analysis programs, or used as test data 
to drive programs that are being developed- A 10-byte header is added 
to the data; otherwise, it is not changed in the recording playback 
sequence. 

Both data recording and playback can be invoked in a single realtime 
job in one of two ways- 

1- the two functions can use different data sets; that is, the 
playback can be from a data set that was recorded on a previous 
run and new data written on another data set. 

2- the record function can be invoked, and the playback routine 
can be invoked for the same data set. 

An example of the DRECOUT and DPBIN DD cards needed for the second case 
are as follows: 

//DRECOOT DD DSN=US er name, DIS P= (NEW , PASS) ,.. . 
//DPBIN DD DSN=*. DRECOUT, DISP=SHR, 
// VOL=REF=*. DRECOUT 

Figure 2-11 shows the functions of data recording and playback. 



Record 




Data 
Recording 
Routine 




> 




Program 







Data 
Recording 

and 
Playback 
Data Set 



PATCH 
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SYSINIT 

Initialization 
Stream 



Separate 
{Non-Special 
Real Time 
Operating System) 
Job Step 



Playback 
Conversion 
Routine 



User Program 
"LINK" 



Playback 
Routine 



User 
Program 



or 



Special Real Time 
Operating System 
Hex 
Print Routine 



Figure 2-11. Data recording and Playback Processing Overview 



Dat a Recording In itializati on 

The data recording service is initialized at the Special Real Time 
Operating System initialization, so that any RECORD macro issued prior 
to the activation of data recording will be non-operational with a 
return code of 04. During realtime operation, the writing of data can 
be suppressed or enabled by the user. Data recording is enabled or 
disabled by an input message processing command. 
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•DREC ) .ENABLE 
.DISABLE 



,ALL ) 
,ADD 
.DEL ! 



[ id.id. 



DREC 


Informs the input message 
this reply is for data rec 


ENABLE/DISABLE 


Causes data recording to b 
QLXsaDjLeua uxsauxe jLs^uxire 


ADD 


Causes the following ID (s) 
Recording Table- Up to 20 
the table. 


DEL 


Causes the following ID(s) 
Data Recording Table. DEL 
causes all IDs to be delet 


ALL 


Causes all IDs to be enabl 


id 


A three-digit hexadecimal 
data is to be recorded. 



Da t a Reco rdin g 

Requests to record data for later playback are passed to the data 
recording function by the RECORD macro. With this macro, the user 
supplies an ID= (X '001-FFF •) r the address (ADDR=) of the data, and the 
court (COUNT=) of bytes of data to be recorded (value of 1 to 65525), 
The data is written to a sequential data set defined by the user and 
is recorded on fixed length records. If the request is to record more 
data than will fit on one record, the data is split into two or more 
records to be reassembled into a single record when it is read back. 

The data is time-tagged upon receipt (execution of the RECORD macro) 
and recorded in chronological order. 

Data recording requests cannot span the partition boundary, so recording 
must be enabled in the partition where the program executing the RECORD 
macro resides. Recording may be enabled in both the MASTER and SLAVE 
partition simultaneously. When a given ID is enabled (either explicitly 
by entering that ID or implicitly with the ALL option) it is enabled 
for all programs in that partition. It is the responsibility of the 
user to select IDs that identify the source of the data and be 
meaningful when played back. 

The following DD card is required by data recording: 

//DRECOUT DD defines a sequential data set to which the data will be 
written. 

This data set will be opened (QSAM, LOCATE mode) when data recording 
is enabled and closed when data recording is disabled. Standard JCL 
conventions apply to this data set, and the user should be aware of 
the effect of all of the parameters that are specified. Some of the 
DD card parameters by which the user may affect data recording operation 
are as follows: 

DISP= If anything except MOD is specified, each time data 

recording is enabled, data will be written at the 
beginning of the data set. This may have the effect of 
over-writing data which was recorded by previous 
ENABLE/DISABLE sequences. 
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DCB=BLKSIZE= 



DCB=B0FNO= 



Defines the size of records written and QSAM buffers. 
The data is packed vithin the buffer by data recording. 
Specifying a large block size will reduce the number of 
I/O accesses but increase virtual storage use. A block 
size of less than 200 bytes is not recommended. If not 
specified, a block size of 2K bytes will be used; if 
specified, LRECL should be the same as BLKSIZE. 

Specifies the number of buffers to be allocated by QSAM 
and, consequently, will affect the amount of waiting 
for I/O by the RECORD function. If not specified, three 
buffers will be allocated. 



£^la Play back 

The data which has been recorded by the data recording facility may be 
read and passed to a user-supplied routine or to the Special Real Time 
Operating System hex data print (hex dump) routine based on time and 
IDs (which were assigned at data recording tine). 



The user specifies to the playbac 
(start and stop times) for which 
name of a user-supplied load modu 
to the playback routine. If no u 
the default processing routine is 
hex data print routine. The user 
to the user's needs. The hex dat 
of the recorded data in a format 
data, when passed to a user load 
f orma t: 



k routine th 
data is to b 
le for data 
ser processi 
the Special 
module may 
a print rout 
similar to t 
module, will 



e data IDs and time range 
e processed. Also, the 
processing may be specified 
ng module is specified. 

Real Time Operating System 
process the data according 
ine will supply a hex dump 
hat of an ABEND dump. The 

be in the following 



Header 



FLG 


ID 


LGTH 


TIME 



REC 



User Data 



The header is a 10-byte field where FLG is four bits of flags set by 
data recording, ID is a 12-bit field that contains the identification 
supplied by the user, and LGTH is a 2-byte field which contains the 
length of the entry (including this 10-byte header). TIME is a U-byte 
field that contains the time (in packed decimal format) that the data 
was recorded. User data is the data passed by the user. REC is data 
recording control data. 

The playback routine may be invoked by any of three methods: 

1. Through the Special Real Time Operating System initialization 
routine by PATCH control cards 



As a separate (non-Special Real Time Operating System) job step 

Through a LINK issued by a job running under the Special Real 
Time Operating System.. 
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The following DD cards are required by data playback: 



//DP BIN DD 



Defines a sequential data set which contains 
data recorded by the RECORD macro. 



//SRTODUMP DD Defines a sequential (printer) message data 
set- 



Playback Via Patch Contro l Card 

To invoke data playback at the Special Real Time Operating System 
subsystem initialization time through the use of a PATCH statement, 
the PATCH statement should be coded as shown: 



I label] PATCH EP= DPPXPCON, [TASK = name, ] lQL = nJ 
[lD = n,] 



See the section entitled "Special Real Time Operating System 
Initialization" for a complete description of the PATCH control 
statement. Only the parameters required by data playback are described 
here. 

In some of ti. -=> following parameter definitions, a zero has special 
meaning. In tnese cases, the parameter should be specified on the 
PATCH statement as a nuraer ic value, using the F or X format (i.e., 
specified as F»0* rather than C'O')- 

DPPXPCON 

Is the entry point of the playback conversion routine that converts 
the specified parameters to a form recognized by data playback and 
then passes the converted parameters via LINK to data playback. 

STARTDATE 

A date in the form of DD/HMM/YY (where DD is the day, MMM is the month 
(first three letters of the month are specified) , YY is the year) 
specifies the day to start the playback process. Zero specifies that 
data playback is to start at the beginning of the data 
recording/playback data set. The characters 'ALL' specify that the 
entire data recording data set is to be played back. If ALL is 
specified, all other parameters are set to zero except the LM 
parameter. 

STAfvTIME 

Specifies the start time of data playback on the start date specified. 
Tinie is in the form of HHMMSST (where HH is hours, MM is minutes, SS 
is seconds, and T is tenth of seconds) . 

STOPDATE 

A date, in the same format as STARTDATE, for which the last date is 
to be processed. Zero specifies that data recording is to stop at 
the end of the data record ing/ pi ay back data set. 

STOPTIME 

Specifies the latest time on the date specified for which recorded 
data is to be processed. Time is in the same format as STARTIME. 




PARM = (C ''STARTDATE' , C'STARTIME', 
C 'STOPDATE C 'STOPTIME ' , 
C'LM',C'COUNT',C'IDr, C'lDlA', 
C'ID2' , C'ID2A' , C'ID3' , C'1D3A' ) 



APPLICATION SERVICES 2-57 



Is an 8-char<icter entry point name of a load module to vhich data 
playback will pass the recorded data. If less than ei^ht characterSr 
it must be padded on the right with blanks. Zero specifies that the 
recorded data will be passed to the Special Real Time Operating System 
hexadecimal data print routine. 



ID Count 

Is the number of ID pairs (01-20) specified. 
ID pairs is 20. 



The maxijhum numi>er of 



IDn-IDm 

Specifies a range of IDs to be played back within the time frame 
specified. IDn is the lowest ID in the range, and IDo is the highest 
ID in the range. If only one ID is to be playad back, IDn and IDm 
must be identical. ID (001-FFF) is a three-digit hexadecimal nuBl»er. 

Example 1 shows three different patch cards for invoking data playback. 

EXAMPLE 1: 



// 
// 
// 

// 



EXEC PGM=DPPINIT 

DD cards required by the Special Real Time 
Operating System Initialization 



//SysiNIT DD * 

PI PATCH EP=OPPXPCON,TASK=DPPXPCON, 

QL=5 ,1 D=7 , PRTY=JGBST EP-1 5 , 
PARAN= (C09/J AN/73* ,C« 15202 07«, 
C» 09/FEB/73* ,C 1730412' ,C«TESTflODE' , 
C»02V,C»F20« , C«F76«, C« 00 1 • ,C '5 10 • ) 

P2 PATCH EP=DPPXPCON,TASK=DPPXPC0Nr 

PARAM= (X»0' ,C« 1521459* ,X»0 • , 

C« 16 43 782* ,X«0«,C« 01 * rC* 100 • ,C * 200 • ) 

P3 PATCH EP=DPPXPCO»,TASK=DPPXPCON, 

QL = 1 0 , ID= 9 , P RT Y= JO fiSTE P- 1 0 , 
PARA«= (C* ALL*, X*0* ,X«0*,X*0*, 
C TEST MODE •) 

These three PATCH statements will cause data playback to be entered 
three times- PATCH statement PI will cause any data recorded between 
15 hours, 20 minutes, 20-7 seconds (3:2 0:20.7 pm) on January 9, 1973 
and 17 hours, 30 minutes, 41.2 seconds (5:30:41.2 pm) on February 9, 
1973 which has record IDs F20 through r76 or 001 through 510 to be 
passed to user load module TESTMODE. 

PATCH statement P2 will cause all recorded data that has an ID 100 
through 200 and was recorded between 15 hours, 31 minutes, 45.9 seconds 
and 16 hours, 43 minutes, and 78.2 seconds to be dumped to a SYSOUT 
data set by the Special Real Time Operating System raw data print 
routine. Because no dates are specified^ the data set will be searched 
for the first data which has a time greater than the STARTIME, 
regardless of date and processed through the first data with a time 
greater than the STOPTIME regardless of date. 

PATCH statement P3 will cause all data on the data set to be passed to 
load module TESTMODE. See the Special Real Time Operating System 
Initialization in Chapter 3, for a cojsplete description of the PATCH 
cards. 
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Playback as a Separate Jobstep 

When run as a separate (non-Special Real Time Operating System) job 
step, either in a baclcground partition or on an offline CPO, the 
parameters are passed to the data playback non-realtime initialization 
through the PARH parameter of the JCL EXEC statement. 

//stepname EXEC PGM=DPPXNRTI , 

PARM = ' ST ARTD ATE, STAR TIME, 
STOPDATE,STOPTIME, 
LM,C00NT,ID1 , 

ID1A,ID2,ID2A, 
ID3,ID3A, • 



stepname 
Is the name of the job step« 

DPPXNRTI 

Is the name of the non-realtime Special Real Time Operating System 
program to which the parameters will be passed. 

STARTDATE, STARTTIME, STOPDATE, STOPTIME, LM, COUNT, ID 
Have the same meaning as described for PATCH control statement. 

Note: Every playback parameter must be specified except when ALL is 
specif ied. 

When ALL is passed to the non-realtime playback routine (DPPXNRTI) with 
a load module name, the parameters should be in the following format: 

//stepname EXEC PGM=DPPXNRTI,PARM=' ALL bbbbbb, LM « 

where ALL is followed by six blanks as the first parameter and the load 
module name as the second parameter. 

The fields within the PARM string are positional, and each field must 
occupy the exact number of positions allocated to that field as follows: 

STARTDATE 9 

STARTIME 7 

STOPDATE 9 

STOPTIME 7 

LM 8 If a Load Module name is specified or 
1 if zero is specified 

COUNT 2 

ID 3 each 

All fields must be separated by commas^ 

In examples 2 and 3 the Special Real Time Operating System playback is 
run as a separate (Non- Special Real Time Operating System) job step. 

EXAMPLE 2: 

// EXEC PGM=DPPXNRTI, 

PARM='07/J AN/73, 0800000, 07/FEB/73, 
090000 0^ 0,02,020,025,040,050 • 

All data that has an ID in the range 020 through 025 and 040 through 
050 and that was recorded after 08:00:00.0 on January 7, 1973 and 
09:00:00.0 on February 7, 1973 will be printed by the Special Real Time 
Operating System raw data print routine- 
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EXAMPLE 3: 



// EXEC PGM=DPPXNRTI» 

PARM=» ALLbbbbbb, TESTMODE* 



All data on the data set will be passed to load module TESTWODE. 



PlaybacJ: Via Link 

The LINK macro instruction may be used to invoke data playback. The 
LINK macro should be in the following format: 



EXAMPLE 


CSECT 






in struct ions 


symbol 


LINK 


EP=DPPXDPB,PAB AM=(PARn) 




or 






LA 


R, PARM 




LI NK 


EP=DPPXDPB ,PARAn=((F)) 






instructio ns 


FARM 


DS 


OF 


ST ABTDAT 


DS 


CL9 


STARTTIM 


DS 


PL 4 


STOPDATE 


DS 


CL9 


STOPTIME 


DS 


PL 4 


LM 


DS 


CL8 


IDCOUNT 


DS 


AL2 


ID1 


DS 


XL 2 


ID1A 


DS 


XL 2 


ID2 


DS 


XL 2 


ID2 


DS 


XL 2 


ID2A 


DS 


XL 2 


ID3 


DS 


XL 2 


ID3A 


DS 


XL 2 


R 






Is a general 


purpose 


register. 


DPPXDPB 






Is the data 


playback 


entry point name. 



PARM 

Is the address of the playback parameters. 
The playback parameters for the LINK should be in. the following format: 



Bytes Field Name Field Description, Contents, Meaning 

9 STARTDAT 

a STARTTIM 

9 STOPDAT 

a STOPTIME 

8 LM 

2 IDCOUNT 

2 ID 

2 ID 



additional IDs in pairs 
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Examples 4 and 5 show a LINK to the playback function from a user coded 
program. 

EXAMPLE 4: 

EXAMPLEa CSECT 

instructions 
LINK EP=DPPXDPB,PARAM= (PARH) 



DS OF 

PARM DC CL9« 09/JAN/7 3» 

DC PL4* 1540071' 

DC CL9' 09/FEB/73' 

DC PL4M650509» 

DC CL8» TESTMODE' 

DC AL2(3) 

DC XL2« 11 1« ,XL2«222« 

DC XL2» 100;XL2' 11 0» 

DC XL2» FFO« ,XL2»FFF» 

END 



A job running under the Special Real Time Operating System will LINK 
to the Special Real Time Operating System data playback routine. All 
data that has an ID in the range 111 through 222, 100 through 110, and 
FFO through FFF and that was recorded between 15 hours, 40 minutes, 
07.1 seconds and 16 hours, 50 minutes, 50.9 seconds on 09 /JAN/73 will 
be passed to load module TESTMODE. 



EXAMPLE 5: 

EXAMPLE5 CSECT 

instructions 
LA 1,PARM 

LINK EP=DPPXDPB,PARAM= ((1) ) 



PARM DS OF 

DC CL9'ALL' 

DC PL4'0« 

DC XL9'0' 

DC PL4«0« 

DC CL8» TESTMODE' 



A job running under the Special Real Time Operating System will LINK 
to the Special Real Time Operating System data playback routine. All 
data in the data set will be passed to load module TESTMODE. 



HIGH-LEVEL LANGUAGE INTERFACES 

The Special Real Time Operating System routines provide an interface 
to allow PL/T and FORTRAN users to use most of the services provided 
by the Special Peal Time Operating System. The interface routines are 
independent of the compiler level or the optimizing compilers. Figure 
2-12 lists the Special Real Time Operating System macros supported by 
the interface routines for PL/I. The macros in the figure are also 
supported for FORTRAN, but there are no default structures. 
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PUTBLOCK 


24 


BLOCKSTR 


BLOCKDEF 


MESSAGE 


40 
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44 
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48 
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Figure 2-12. Macros Supported by PORTRAN-PL/I Interface Routines 

All interface routines are invoked as shown in Figure 2-13. The 
parameters are passed using standard linkage conventions to the 
assembler language interface routine. The interface routine adjusts 
the parameter list and then issues an execute form of the appropriate 
macro to invoke the desired service. After the service routine has 
completed execution, the interface routine stores the return code for 
use by the calling program and returns to the caller. 
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Figure 2-13. High-Level Language Interfaces for the Special Real Tiie 
Operating System Services 

The high level language user must refer to the Special Real Time 
Operating System macros section when using the language interfaces, as 
more details are given with each macro description. 



The SEecial Real Time Operating S ystem- PL/T Interface 

The PL/I interfaces to the Special Real Time Operating System services 
are designed to be independent of the PL/I compiler used. This means 
"dope vectors" or "locator/descriptors" are not referenced by the 
interface routines. To avoid referencing "secondary" pointers, the 
parameter of a CALL statement must point to the first element of the 
structure defining the parameter list. 

DCL 1 PATCHSTR, 
2 MACID, 
2 EC, 



For example, given the above structure, the call stcitement would have 
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to be CALL DP PPIF (PATCH STR. M ACI D) for the correct parameter list to be 
passed to the interface routine DPPPIF. 

All Special Real Time Operating System services invoked by a PL/I 
program have unique parameter lists which can be described by a 
structure- An aid to the PL/I .programmer are default structure 
definitions. The programmer may invoice them through the compiler 
preprocessor option - %INCLODE- A list of the PL/I structure 
definitions and names is included in Figure 2-12. Each of the default 
structures is explained in the following sections describing the Special 
Real Time Operating System services provided for PL/I programs. Any 
option changes made by the PL/I program to a default structure must be 
reset if the structure is reused and the option is not desired. 

In addition, users of the default structure will notice the two fields 
(MACID and RC) at the beginning of each. They are common to every 
structure used as a parameter when calling DPPPIF, MACID is initialized 
in the default structures with the correct value to tell the interface 
routine which service is being requested. RC is where the return code 
from the service routine is stored. 

PL/I programs in a normal 0S/VS1 job shop environment are initiated, 
the PL/I Prolog routines and the user program are executed, and at 
termination the PL/I Epilog routine is executed. In a realtime 
environment where the PL/I program is to be cyclically executed, the 
PL/I Interface routines provide facilities to allow the PL/I program 
to keep its resources across cyclic executions and to execute cyclically 
without incurring the overhead of Prolog and Epilog for each execution 
following the initial execution. This facility applies only to 
independent tasks that are PATCHed with the EP= parameter specifying 
the same EP name. Figure 2-14 shows the coding of a PL/I program using 
this facility. 



PL/I PROC.RAM 



PL/I PROLOG 



LOOl': 



CALL DPPPARM (PARMSl RID); 
II' RI. ICI) = 0 rill'N Rin URN; 



GO lO LOOP: 
I'M); 



_ IM./i PROGRAM 

AS coni;i) BY usr- R 



PL/1 EPILOG 



Figure 2-1U. PL/I Example 
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The following is a series of PATCHes to PL/I prograas which will 
illustrate when a program would be forced through Epilog. 



A 


PATCH 


TASK=A 


,EP=PLIPROG 


B 


PATCH 


TASK=A 


,EP=PLIPROG 


C 


PATCH 


TASK=A 


,EP=PLIPROG 


D 


PATCH 


TASK=A 


,EP-PLIEXMP 


E 


PATCH 


TASK=A 


,EP=sPLIPROG 


F 


PATCH 


TASK-A 


rEP=PLIEXMP 


G 


PATCH 


TASK=A 


,EP=PLIEXMP 



where: PLIPROG and PLIEXMP are PL/I programs coded as shown in the 

previous example, 

PATCH A executes Prolog for PLIPROG, then the body of PLIPROG. When 
the body finishes, a second CALL is made to DPPPARM. PATCH 3 then 
executes without going through Prolog. PATCH B in turn finishes and 
again calls DPPPARM. PATCH C then executes - again without going 
through Prolog. When PATCH C finishes, another call is made to DPPPARM. 
The PL/I interface routine determines that the next PATCH (D) is to a 
different program. A non-zero return code forces PATCH C to terminate 
and thus execute PL/I Epilog. PATCH D then executes, going through 
PROLOG and the code body for PLIEXMP- PATCH D finishes and again calls 
DPPPARM- Once again, the interface recognizes that the next program 
to be executed is different and returns a non-zero return code. Program 
DPPEXMP is forced through Epilog. PATCH E passes through both Prolog 
and Epilog and PATCH F passes through Prolog and PATCH G executes 
without Prolog. Then, on the next call to DPPPARM, Task A is placed 
in a wait state until another PATCH to it is received. 



£iICHiio::PL/l Interface 

PL/I programs cannot easily retrieve parameters passed via register 1. 
To obtain the parameters in a PL/I program invoked by PATCH, an 
interface routine DPPPARM and a structure PARMSTR, which may be copied 
into the PL/I program by %INCLaDE PARMDEF; are provided. The following 
PL/I statements define PARMSTR: 



1 


PARMSTR, 






2 


ID FIXED BIN INIT(O) , 


/* 


RESERVED */ 


2 


RETCD FIXED BIN INIT(1), 


/* 


0 IF PARMS CHANGED */ 


2 


XCVT POINTER, 


/* 


A (XCVT) V 


2 


RESOURCE POINTER, 


/* 


A (RESOURCE TABLE) */ 


2 


FARMS POINTER; 


/"^ 


A (PATCH PARAMETERS) ♦/ 



PARMSTR 

Is the name of the structure used to obtain the PATCH problem 
parameters. 

ID 

Is reserved halfword initialized to zero. 

RETCD 

Is a halfword binary number indicating the validity of the pointer 
value in PARMS. If not zero, the PL/I program should not use the 
address in PARMS and should return control to the system. If zero, 
PARMS contains a valid address. 

XCVT 

Specifies the address of the Special Real Time Operating System 
control block XCVT. 
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RESOORCE 

Specifies the address of a tvo fallvord area available to all prograas 
executing under the current task. 

P&RHS 

Specifies the address of the problea paraaeters being passed by a 
P&TCH to the prograa. 

The PL/I prograa using this interface aust declare the structure only 
once and in the highest block. The structure aust be reused without 
reinitializing. If the prograa CJlLLs for another set of PATCH 
paraaeters and the task vork queue is eapty, the prograa vill be placed 
in a wait until a PATCH is issued for the task. 

The exaaple below is the proper aethod for using the structure. This 
exaaple uses the default structure PARHSTB to obtain the PATCH pointers. 
The structure defining the paraaeter list is based on the PARHS pointer 
variable. Note that the PL/I prograa loops back to the CALL statessant 
and that the only exit occurs if the return code froa DPPPARH is net 
zero. This ainiaizes the execution of PL/I Prolog and Epilog. 

DCL 1 PARHSTR, 

2 ID FIXED BIM IHIT(O) , 

2 RETCO FIXED BIH IMIT (0) , 

2 XC?T POIMTER, 

2 RESOORCE POIHTER, 

2 PARHS POIMTEB; 

DCL 1 PARiHETBR BASED (PARHS), 
2 LBRG FIXED BIB, 
2 PATCHID FIXED BIB; 

LOOP: 

CALL DPPPARH (PABHSTR. ID) ; 
IF RBTCD =70 THEM RBTORN; 

no rial ezeciatioo 



GOTO LOOP; 
END prograa; 



The default structure which defines the paraaeter list for invoking 
the PATCH service aay be copied into the prograa by %INCLODB PATCHDBP. 
The PL/I stateaents and definitions are listed as follows: 
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1 


PATCHSTR, 


/* 


PATCH STROCTORE ♦/ 




2 


MACID FIXED BIN IHIT(O), 


/* 


PATCH HACRO ID */ 




2 


RC FIXED BIN INIT(O) , 


/♦ 


RETURN CODE V 




2 


PACHPARM POINTER, 


/* 


A(PARA«ETERS) */ 




2 


TASKNAME CHAR(8) INIT(» ') 


/♦ 


TASKNAME */ 




2 


EPNAflE CHAR(8) I N IT ( • I EF BR 1 4 » ) 


, /* 


LOAD nODULE »/ 






NAME CHAR(8) INIT(' •) 


/* 


RELATIVE TASK OF VALUE 


*/ 


2 


QOEOE FIXED BIN INIT(1), 


/♦ 


DEFAULT = 1 */ 




2 


VALUE FIXED BIN INIT(O), 


/♦ 


DEFAULT = 0 V 




2 


ECB POINTER, 


/* 


ECB ADDRESS */ 




2 


FPBEL FIXED BIN{31,0) INIT(O), 


/* 


RESERVED ♦/ 




2 


PPEEA FIXED BIN(31,0) INIT(O), 


/* 


RESERVED ♦/ 




2 


TCEX FIXED BIH(31,0) INIT(O), 


/* 


TCB EX TE MS ION */ 




2 


PFLAGS 


/* 


FLAG OPTIONS IF BIT IS 


SET OH 




3 (FO, 


/* 


RESERVED »/ 






HASTER, 


/* 


PATCH HASTER PARTITION 


♦/ 




SLAVE, 


/♦ 


PATCH SLAVE PARTITION 


♦/ 




F3, 


/* 


RESERVED */ 






REPCH, 


/♦ 


ECB REPATCH */ 






QPOS, 


/* 


QPOS=FIFST V 






DPCH, 


/* 


QPOS=D PATCH V 






DEL) BIT (1 ) IBIT (• 0» D) ; 


/* 


EP DELETE */ 





PATCHSTR 

The naae of the default structure. 



BACID 

Specifies the halfvord binary value set to zero to identify the PATCH 
service request. 

PC 

Specifies a halfword binary field containing the return code froa 
the service routine. The return codes are described in the PATCH 
■aero definition. 



PACHPARH 

Specifies the address of a paraneter list being passed. The format 
is a half word binary value (lininua value is 4) describing the length 
of the entire parameter list, followed by a halfvord binary value 
from 0 to 255 called the PATCH ID with the remainder of the list 
being the parameters. The diagram below represents the format of a 
PATCH parameter list. 

Note: If the list is greater than 8 bytes, the interface routine will 
move it to a GETMAIN area to be freed when processing of the 
work queue is completed. 



2 

length PATCH ID 



parameters 



TASKNAHE 

Specifies a 1 to 8 character name »hich is the name of the task being 
referenced by this PATCH. If the task does not exist, one by that 
name will be created. 

EPNAHE 

Specifies a 1 to 8 character valid program name which is the name of 
the program to be scheduled under the task being created with the 
PATCH. 
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NAME and VALUE 

Specifies a task name and a value which will determine the priority 
of the new task. VALUE will be subtracted from the dispatching 
priority of t,he specified task. VALUE may range from 0 to 255 with 
zero default. See PRTY option of PATCH macro for further detail. 

QUEUE 

Specifies the number of work queue entries to be provided for the 
new independent task. Any decimal value from 0 to 255 may be 
specified. The default value is 1. A work queue entry provides 
space to queue PATCHes which have not been executed by the task. If 
0 is specified as the queue length, the task accepts one PATCH, works 
on that request, and when completed, waits for the next request. If 
a PATCH is issued for that task while the task is busy, it is not 
executed. If the queue length is 1 , the task can accept one PATCH 
even while it is busy. Any PATCH parameters waiting in the queue 
when a task completes processing the current request will be executed 
one at a time, with the top of the queue executed next- This 
procedure is the same for all queue values from 0 to 255. 

ECP 

Specifies the address of the EC B within a WAITSTP which is to be used 
in a CALL DPPPIF. This ECB is posted when processing for this PATCH 
is completed. The BEPCH flag causes the ECB to be posted with the 
address to be used in the REPATCH macro if this PATCH is not executed 
because of a DPATCH or a QPOS=FIRST PATCH with the queue full- 
Default is no ECB. See PL/I PATCH WAIT, 

FREEL and FREEA 
Are reserved. 

TCBX 

Specifies the address of the TC B extension control block (TCBX) for 
an existing independent task. The TCBX address is returned in 
structure after each PATCH. Use of this operand with all PATCHes to 
the same task after the initial PATCH will reduce system processing 
time. Note that other parameters must still be specified for 
verification or in the event the task has been DPATCHed. 

PFLAGS 

Are PATCH option flags as described below: 

FO and F3 
Are reserved, 

MASTER 

Specifies this is a PATCH to the MASTER partition. 
SLAVE 

Specifies this is a PATCH to the SLAVE partition. 
REPCH 

Specifies that the ECB will be posted when a BEPATCH control block 
is built. Default is no REPATCH control block. 

QPOS and DPCH 

Specifies in the task work queue where this work request is to go 
if the task is busy. If QPOS is on, the request is to be placed so 
as to be processed before those already on the queue. If DPCH is 
on, the processing for this PATCH will not be executed until a' DPATCH 
is issued for this task. Default is last on the work queue- 

DEL 

Specifies that a DELETE is issued for the EP name after processing 
completes for this PATCH. Default is no. 
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The Special Real Time Operating system PATCH service may be invoiced by 
including the PATCHDEF in the PL/I program, completing the required 
information within the structure including building a parameter list 
and calling the interface routine DPPPIF with the PATCHSTP. Examples 
of using the PATCH facility follow. 

In Example 1, structures are declared for a parameter list and the 
PATCH structure. The task DPPZTSOO is created with a queue length of 
1. Program DPPZTS13 is executed, and the parameter list contains only 
the length field and a PATCH ID of 10, The new task must have the same 
priority as the task issuing the PATCH. The PATCHing program does 

not want noti f ication of the completion of the PATCH, Note that if 
the task already exists, the PFLAGS indicate this work request will be 
queued behind any others on the queue. 



DCL 1 PARAMETER, 

2 LENG FIXED BIN, 

2 PATCHID FIXED BIN, 

2 PARAMS (10) FIXED BIN (31,0); 

DCL 1 WAITSTR, 

2 MACID FIXED BIN INIT (60), 

2 RC FIXED BIN INIT (0), 

2 ECBX FIXED BIN (31,0) INIT (0) ; 



^INCLUDE PATCHDEF; 



DCL 1 PATCHSTR, 

2 MACID FIXED BIN INIT (0) , 

2 RC FIXED BIN INIT (0) , 

2 PACHPARM POINTER, 

2 TASKNAME CHAR(8) INIT (» «) 

2 EPNAME CHAR (8) INIT ('lEFBRI^' 

2 NAME CHAR(8) INIT(» •) , 

2 QUEUE FIXED BIN INIT(1), 

2 VALOE FIXED BIN INIT (0) , 

2 ECB POINTER, 

2 FREEL FIXED BIN(31,0) INIT(O), 
2 FREEA FIXED BIN(31,0) INIT(O), 
2 TCBX FIXED BIN (31,0) INIT(O), 
2 PFLAGS. 

3 (FO, 

MASTER, 

SI AVE, 

F3, 

REPCH, 

QPOS, 

DPCH, 

DEL) BIT(1) INIT(«0«B) ; 

LENG = U; 
PATCHID = 10; 

PACHPARM = ADDR (PARAMETER. LENG) ; 

TASKNAME = 'DPPZTSOO'; 

EPNAME = ' DPPZTS13' ; 

CALL DPPPIF (PATCHSTR. MACID) ; 



/* PATCH MACRO ID */ 

/* RETURN CODE */ 

/* A (PARAMETERS) */ 

/* TASK NAME */ 

/* LOAD MODULE */ 

/* RELATIVE TASK OF VALOE */ 

/* DEFAULT = 1 ♦/ 

/* DEFAULT = 0 */ 

/* ECB ADDRESS */ 

/* RESERVED */ 

/* RESERVED */ 

/* TCB EXTENSION */ 

/* FLAG OPTIONS IF BIT IS SET ON 

/* RESERVED */ 

/* PARTITION- MASTER */ 

/* PARTITION=SLAVE */ 

/* RESERVED */ 

/* ECB REPATCH */ 

/* QPOS=FIRST V 

/* QPOS=D PATCH V 

/* EP DELETE */ 



Example 1 

In Example 2, assume that the CALL in Example 1 has returned, and a 
dependent task is to be created at a priority of 10 less than the task 
DPPZTSOO and that program DEPENDX is to be passed a parameter list of 
10 numbers with a PATCH ID of 2. The PATCHing program will wait for 
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the dependent task to complete. The WAIT function is done via a CALL 
to the interface routine using the WAITSTR structure. 



DCL 1 PARAMETER, 

2 LENG FIXED BIN, 

2 PATCHID FIXED BIN, 

2 PARAMS (10) FIXED BIN (31,0) ; 

DCL 1 WAITSTP, 

2 HACID FIXED BIN INIT(60) , 

2 RC FIXED BIN INIT(O) , 

2 ECBX FIXED BIN (31,0) INIT{0); 

9SINCLUDE PATCHDEF; 

DCL 1 PATCH STR, 

2 MACID FIXED BIN INIT (0) , /* PATCH MACRO ID */ 

2 RC FIXED BIN INIT(O), /* RETURN CODE */ 

2 PACHPARM POINTER, /* A (P ARAM ETERS) */ 

2 TASKNAME CHAR(8) INIT(' •) , /* TASK NAME */ 

2 EPNAME CHAR (8) INIT (»IEFBRia«)# /* LOAD MODULE */ 

2 NAME CHAR (8) INIT(' •) /* RELATIVE TASK OF VALUE */ 

2 QUEUE FIXED BIN INIT(1), /* DEFAULT = 1 */ 

2 VALUE FIXED BIN INIT (0) , /* DEFAULT = 0 V 

2 ECB POINTER, /* ECB ADDRESS */ 

2 FREEL FIXED BIN(31,0) INIT(O), /* RESERVED ♦/ 

2 FREEA FIXED BIN (31,0) INIT(O), /* RESERVED */ 

2 TCBX FIXED BIN(31,0) INIT(O), /* TCB EXTENSION */ 

2 PFLAGS, /* FLAG OPTIONS IF BIT IS SET ON */ 

3 (FO, /* RESERVED */ 

MASTER, /* PARTITION=M ASTER */ 

SLAVE, /* PARTITION=SLAVE */ 

F3, /* RESERVED V 

REPCH, /* ECB REPATCH */ 

QPOS, /* EPOS=FIRST */ 

DPCH, /* QPOS=DPATCH */ 

DEL) BIT(1) INIT(»0«B) ; /* EP DELETE */ 



CALL DPPPIF (PATCHSTR. MACID) ;/*EXAMPLE 1*/ 

LENG = HH; 

PATCHID = 2; 

TASKNAME = "; 

EPNAME = • DEPENDX* ; 

NAME = • DPPZTSOO* ; 

VALUE = 10; 

ECB = ADDR (ECBX) ; 

CALL DPPPIF (P ATCH STR. MACID) ; 

IF PATCHSTR. RC <8 THEN DO; 

CALL DPPPIF (WAITSTR. MACID) ; 

END; 



Example 2 



PL/I-PTIME Interface 

The Special Real Time Operating System PTIME service provides two 
different functions, time and PATCH, issued on a time queue basis. 
Therefore, two default structures may be copied into the program by 
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^INCLUDE PTIMEDEF and PTIMPDEF which define the parameter lists for 
the PTIME services- The PL/I statements and their meanings are as 
follows: 



DCL 



1 PTIMPSTB 



/♦ STRDCTOEE FOR PTIME TYPE=RET */ 



/* PTIME SERVICE */ 
/* RETURN CODE */ 



MACID FIXED BIN INIT(4), 
RC FIXED BIN INIT(O) , 
TYPE FIXED BIN (31,0) INIT{0), /* PTIME CALL TYPE */ 
TIME FIXED BIN (31,0) INIT(O), /* CURRENT TIME */ 
TIMDSECT POINTER; 



/* A (TIME ARRAY) */ 



PTIHRSTR 

Is the name of the default structure used to obtain the current time 
and the address of the time array. 

MACID 

Is the half word binary value set to 4 to identify a PTIME service 
request . 

RC 

Is a halfword binary value containing the return code from the service 
request, always 0. 

TYPE 

Is a fullword binary number identifying the PTIME service being 
requested. For this structure, it is For this structure, it is 
always 0. 

TIME 

Is a fullword binary field which will contain the current time of 
day in 10 millisecond units when the interface routine returns, 

TIMDSECT 

Specifies the address of the Special Real Time Operating System time 
array when the interface routine returns. 



DCL 



1 PTIMESTR 

2 MACID 
RC FIX 
TYPE F 
STIME 
ITIME 
ETIME 
PATCH 
2 PA 
2 ST 

3 



SR 
PQ 
3 



INIT(O) 
INIT(O) 



ER 



FIXED BIN INIT (4) , 
ED BIN INIT (0) , 
IXED BIN (31*0) INIT («») , 
FIXED BIN (31,0) INIT(O) 
FIXED BIN (31,0) 
FIXED BIN (31,0) 
POINTER, 
RMS POINTER, 
ART, 

(F0,Fl,F2,F3,Fa, 

SADJFLAG, 

STODFLAG, 
ELFLAG) BIT (1) 
HGE, 

(FO, F1,F2,F3, 

PUSGEI, 
PURGEW, 
PORGEC, 
PURGEU) BIT 
STOP, 
(F0,F1,F2,F3, 

ECNTFLAG, 

EADJFLAG, 

ETO DFLAG, 
ELFLAG) BIT (1) 



INIT ('O' 



(1) INIT ( 



/*PTIME STRUCTURE FOB ADD, MOD, DEL ♦/ 

/* PTIME SERVICE */ 

/* RETURN CODE */ 

/* PTIME CALL TYPE */ 

/♦START TIME */ 

/♦INTERVAL TIME */ 

/♦STOP TIME ♦/ 

/♦A (PATCH SUPL) ♦/ 

/♦A (PARAMETERS) ♦/ 

/♦FLAGS DEFINE STIME CONTENTS */ 

/♦RELATIVE TIME ♦/ 

/♦ADJUSTED TIME ♦/ 

/♦TIME OF DAY ♦/ 
B) , /♦RELATIVE TIME ♦/ 

/♦FLAGS DEFINE PTIME PURGE OPTIONS ♦/ 

/♦RESERVED ♦/ 

/♦DPATCH = I ♦/ 

/♦DPATCH = W ♦/ 

/♦DPATCH = C ♦/ 
O'B) , /♦DPATCH = U ♦/ 



/♦FLAGS DEFINE ETIME GOMTENTS */ 
/♦RESERVED ♦/ 
/♦COUNT VALUE ♦/ 
/♦ADJUSTED TIME ♦/ 
/♦TIME OF DAY ♦/ 
INIT ('O'S); /♦RELATIVE TIME ♦/ 



PTIMESTR 

Is the name of the default structure used to create or modify PATCH 
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service requests by time queue. 



MACID 

Is a halfword binary value set to 4 to identify a PTIME service 
request. 

PC 

Is a halfword binary value containing the return code from the service 
request. If the return code is 8 or larger, the PTIME was not 
successful, and the existing PTIHE specification was not changed. 
The return codes are defined in the macro description. 

TYPE 

Is a fullword binary number specifying the type of PTIME service 
requested. Values may be 4, 8, or 12. If 4, a PTIME queue element 
(PTQE) is created which controls the PATCHes issued according to the 
PTIME request- Since the PTQE exists independently of the creating 
task and may be modified (8) or deleted (12) , the PTQE is referred 
to by task name, entry point name, and the PATCH ID value in the 
passed parameter list. Either task name or entry point name must be 
given for a modify (8) or delete (12) request. However, if only a 
task. name or entry point name is specified, all PTQEs with that name 
are deleted or modified. The default is to create a PTQE (4). 

STIME* 

Is a fullword binary number specifying the time in 10 millisecond 
units of the first PATCH. The flags START specify the value in this 
field. 

SRELFLAG 

If on, the first PATCH will be issued at current time plus the value 
of STIME. 

STODFLAG 

If on, the first PATCH will be issued when current time equals the 
value of STIME. If STIME is less than current time, the PATCH will 
occur the next day- 

SADJFLAG 

If on, the time of the first PATCH is calculated by assuming STIME 
contains the time of day (TOD) , except that the value in ITIME is 
added to STIME until that value is greater than current time. 

ITIME* 

Is a fullword binary number specifying the interval in 10 millisecond 
units between successive PATCHes. 

ETIME* 

Is a fullword binary number specifying when the PTQE is to be deleted. 
The flags STOP identify the value in this field.. 



♦All time values are in 10 millisecond units and must not exceed 24 
hours. 



ECNTFLAG 

If on, ETIME contains a count of the number of PATCHes to be issued 
by this PTQE. 

ERELFLAG* 

If on, ETIME contains a time value in 10 millisecond units, when 
added to the current time equals the stop time. 
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ETODFLAG* 

If on, ETIME contains the stop time m 10 millisecond units. 



EADJFLAG* 

If on, the stop time is calculated by assuming ETIME contains the 
time of day (TOD) in 10 millisecond units, except that the value in 
ITIME is added to ETIME until the value is greater than current 
time. 



♦ Regardless of what value is calculated for a stop time, if it is less 
than the calculated start time (see STIME above) , a 2*»-hour value is 
added to the stop time until the stop time exceeds the start time. 



Note: If all the STOP flags are zero and ETIME is zero, the PTIHE is 

assumed to be infinite, and PATCHes will be issued until a PTIME 
to modify (8) or delete (12) is issued for that task and/or 
entry point name. 

PATCH 

Is the address of the supervisor portion of the PATCH parameters. 
The options provided will be used by PTIME to issue PATCHes based on 
the above time options. If PATCHSTR (the default structure) is used, 
this parameter must point to TASKNAHE. All information desired for 
the PATCH by PTIME must be supplied prior to CALLing the interface 
routine. 



RESTRICTION: Queue Position of DPATCH is not permitted (PFLAGS.DPCH 
set to 1) . 

PARMS 

Is the address of a parameter list to be passed by the PATCH issued 
by PTIME. See PL/I PATCH Interface for format. Note that if this 
parameter list is greater than 8 bytes, the interface routine will 
move it to a GETMAIN area to be freed when the PTQE is destroyed. 

START 

Specifies the start time option flags which define the contents of 
STIME. Only one of the flags must be set. See STIME for flag 
def init ions . 



PURGE 

Is the flag that controls the kind of DPATCH which will be issued 
when the PTQE is destroyed. If no flag is set, no DPATCH is issued. 
Flags at a PTIME delete (12) will override the flags when the PTQE 
was created (4) or modified (8) last. Only one flag may be set. 

PURGEI 

If on, task is deleted regardless of its condition. 



PURGEU 

If on, the task is deleted immediately or ahen the current work 
queue, if executing, completes. Any work queued to the task is 
posted as deleted. 



PORGEC 

If on, the task is deleted only if its work queue is empty. 
PURGEW 

If on, the task will be deleted when the work queue becomes empty. 
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STOP 

Specifies the stop time option flags which define the contents of 
ETIHE. Only one of the flags may be set. See ETIME for flag 
def in.itions. 

The PTIME facilities are invoked by calling DPPPIF with the appropriate 
structure properly completed. Examples presented on the next pages 
use the default structure definitions PTIMESTR and PTIMRSTR (explained 
above), which are copied via %INCLODE PTIMEDEF and %INCLUDE PTIMRDEF, 
respectively. Each example assumes the following PL/I statements: 



DCL 1 PATCHSTR, 

2 MACID FIXED BIN INIT (0) , 

2 PC FIXED BIN INIT(O) , 

2 PACHPAPM POINTER, 

2 TASKNAME CHAR(8) INIT(' ') , 

2 EPNAME CHAR(8) I NIT ( ' I EF BR U ») 

2 NAME CHAR (8) INIT(' ') , 

2 QUEUE FIXED BIN INIT(1), 

2 VALUE FIXED BIN INIT (0) , 

2 ECB POINTER, 

2 FREEL FIXED BIN(31,0) INIT(O), 
2 FREEA FIXED BIN(31,0) INIT(O), 
2 TCBX FIXED BIN(31,0) INIT(O), 
2 PFLAGS, 

3 FO, 

MA STER, 

SLAVE, 

F3, 

REPCH, 

QPOS, 

DPCH, 

DEL) BIT (1) INIT(«0' B) ; 



/* PATCH MACRO ID ♦/ 

/* RETURN CODE */ 

/* A (PARAMETERS) ♦/ 

/* TASK NAME */ 

, /* LOAD MODULE ♦/ 

/* RELATIVE TASK OF VALUE */ 

/* DEFAULT = 1 V 

/* DEFAULT = 0 V 

/* ECB ADDRESS */ 

/* RESERVED */ 

/* RESERVED */ 
/* TCB EXTENSION ♦/ 

/* FLAG OPTIONS IF BIT IS SET ON V 

/* RESERVED */ 

/* PARTITION=M ASTER */ 

/* PARTITION=SLAVE */ 

/* RESERVED */ 

/* ECB REPATCH */ 

/* QPOS=FIRST V 

/* QPOS=DPATCH */ 

/* EP DELETE */ 



DCL 



DCL 



1 PATCHPRM, 

2 LENG FIXED BIN, 
2 PATID FIXED BIN, 

2 PARX (10) FIXED BIN(31,0); 



1 PTIMRSTR, 

2 MACID FIXED BIN INIT (4) , 
2 RC FIXED BIN INIT(O) , 
2 TYPE FIXED BIN (31,0) INIT(O), /* PTIME CALL TYPE ♦/ 
2 TIME FIXED BIN (31,0) INIT(O), /* CURRENT TIME */ 

2 TIMDSECT POINTER; 



/* STRUCTURE FOR PTIME TYPE=BET */ 
/* PTIME SERVICE */ 
/* RETURN CODE */ 



/* A (TIME ARRAY */ 



DCL 1 PTIMESTR, 

2 MACID FIXED BIN INIT(U), 

2 RC FIXED BIN INIT(O) , 

2 TYPE FIXED BIN(31,0) INIT(U), 

2 STIME FIXED BIN(31,0) INIT(O), 

2 ITIME FIXED BIN(31,0) INIT(O), 

2 ETIME FIXED BIN(31,0) INIT(O), 

2 PATCH POINTER, 

2 PAFMS POINTER, 

2 START, 

3 (FO, F1 ,F2,F3,F4, 

SADJFL AG, 

STODFLAG, 

SRELFLAG) BIT (1) INIT('0« 

2 PURGE, 

3 (F0,F1,F2,F3, 
PURGEI, 
PORGEW, 



/* PTIME CALL TYPE */ 

/♦ START TIME */ 

/* INTERVAL TIME */ 

/* STOP TIME V 
/* A (PATCH SUPL) */ 
/* A (PARAMETERS) */ 

/* FLAGS DEFINE STIME CONTENTS */ 

/* RESERVED */ 

/* ADJUSTED TIME */ 

/* TIME OF DAY */ 

B) , /* RELATIVE TIME ♦/ 

/* FLAGS DEFINE PTIME PURGE OPTIONS 

/* RESERVED */ 

/* DPATCH=I V 

/* DPATCH=W */ 
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PURGEC, /* DPATCH=C */ 

PDRGEU) BIT(1) INIT(»0»B), /* DPATCH = 0 */ 



STOP , /* 

3 (FO, F1,F2,F3, /* 

ECNTFLAG, /* 

EADJFLAG, /* 

ETODFLAG, /* 

ERELFLAG) BIT (1) INIT(»0«B) 



FLAGS DEFINE ETIME CONTENTS */ 
RESERVED */ 
COONT VALOE V 
ADJUSTED TIME */ 
TIME OF DAY */ 
; /* RELATIVE TIME */ 



DCL 1 TIMED BASED (TIHDSECT) , 
2 TIMEHS FIXED BIN (31,0), 
2 TIMETOD FIXED BIN(31,0), 
2 TIMEJDAY FIXED DEC (7,0), 
2 TIMEHDAY FIXED DEC(7,0), 
2 TIMEEBC CHAR (10) , 
2 TIMEBDAY FIXED BIN; 



EXAMPLE 1: In the first example, the program uses the default structure 
PTIMRSTR to obtain the current time. Note, that as a result of the 
CALL, the time array structure TIMED is usable since its base variable 
(a POINTER variable in PTIMRSTR) has been set. The current time is 
used to set the start time in PTIMESTR for PATCHes by PTIME, at current 
time plus 1 hour. The interval is set to 1 hour, and the last PATCH 
is to occur 3 hours later. The PATCH parameters are set to create the 
task TIMETEST with a work queue length of 5, and a dispatching priority 
of 15 less than the PTIME task. The PATCH will execute program TTEST 
and delete it when the processing of each work request completes. The 
parameters passed are day of the year and time of the PTIME request 
with a PATCH ID of 10. 



CALL DPPPIF(PTIMRSTR.MACID) ; 
PATCH = ADDR (PATCHSTR. T ASKNAME) 
PARMS = ADDR (PATCHPR M, LENG) ; 
STIME = TIME+360000; 
STODFLAG = • 1 • B ; 
ITIME = 360000; 
ETIME = STIME+ 1080000; 
ETODFLAG = • 1 ' B; 
TASKNAME = 'TIMETEST*; 
QUEUE = 5; 
VALUE = 15 
EPNAME = 'TTEST* 
DEL = ' 1 'B 
LENG = 12; 
PATID = 10 
PARX (1) = TIMEBDAY ; 
PARX(2) = TIME; 
CALL DPPPIF(PTIMESTR.MACID) 



/* CURRENT TIME */ 
/* BUILD THE PTIME */ 
/♦ PARAMETERS */ 



/♦ BUILD THE PATCH */ 
/* PARAMETERS */ 



/♦ BUILD THE PROGRAM */ 
/* PARAMETERS ♦/ 



/* ISSUE THE PTIME */ 



EXAMPLE 2: For the second example, the PTQE built by Example 1 will 
be modified (TYPE = 8) to start the PATCHes 15 seconds after this PTIME 
is issued, the interval to once a minute, and the stop time to never 
end. The program will not be deleted when a work request is finished 
processing and the work request will be queued first- The PATCH ID 
will be changed to 5. Note, that all parameters must be re-specified, 
as a modify acts as a replace. All structures are initially default. 
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TYPE = 8; 

PATCH = ADDR (PATCHSTR. TASKNAME) ; 

PARMS = ADDR (PATCH PR n, LENG) ; 

STIME = 1500; 

SRELFLAG = • 1« B; 

ITIME = 6000; 

TASKNAME = 'TIMETEST'; 

QUEUE = 5; 

VALUE = 15; 

EPNAME = ' TTEST' ; 

QPOS = 1 ; 

LENG = 12; 

PATID = 5, 

PARX(1) = TIMEBDAY: 

PARX (2) = TIME; 

CALL DPPPIF (PTI MESTR. MACID) ; 



/* MODIFY PTQE */ 



/* BUILD PATCH PARAMETERS ♦/ 



/* BUILD PROGRAM PARAMETERS */ 



/* ISSUE PTIME V 



EXAMPLE 3: Example 3 shows the use of the adjusted time facility of 
PTIME. The first PATCH is to occur at 5 a.m. or within 30 minutes of 
when the PTIME was issued and at 30-ffiinate intervals for 6 times- The 
task is to be deleted immediately when the PTQE is destroyed. 

PURGEU = '1»B; /* BUILD PTIME PARAMETERS */ 

STIME = 1800000; 

SADJFLAG = • 1 • B; 

ITIME = 180000; 

ETIME = 6; 

ECNTFLAG = ' 1» B; 

PATCH PARAMETERS 



PROBLEM PARAMETERS 



CALL DPPPIF(PTIMESTR.MACID) ; /* ISSUE PTIME */ 



EXAMPLE 4: Example U is the example for deleting a PTQE. Since the 
function of this PTIME service request is to locate the PTQE which is 
to be destroyed, only the parameters required to identify the PTQE need 
be given. In this case, the task is to be DPATCHed as well. 

PURGEU = M • B; 
TYPE = 12; 

PATCH = ADDR (TASKNAME) ; 
PARMS = ADDR (LENG) ; 
TASKNAME = 'TIMETEST'; 
EPNAME = • TTEST' ; 
PATID = 10; 

CALL DPPPIF(PTIMESTR.MACID) ; 
This example would remove the PTQE created by Example 1. 
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EL/IZ-DPATCH Interface 



The Special Real Time Operating System DPATCH facility provides the 
programmer the method for destroying tasks which were created by the 
PATCH service. 



A PL/I interface exists to provide a DPATCH service. The default 
structure, DPACHSTR, shown below, may be Copied into the PL/I program 
by a %INCLUDE DPACHDEF. 



1 DPACHSTR, 

2 MACID FIXED BIN INIT (8) 
2 RC FIXED BIN INIT (0) , 

2 TYPE fIXED BIN INIT(O) , 
2 TASK CHAR (8) INIT (« ' ) ; 



/* DPATCH STRUCTURE */ 

/* DPATCH ID */ 

/* RETURN CODE */ 

/* DEFAULT PURGE = U */ 

/* TASK NAME */ 



DPACHSTR 

Specifies the name of the default structure used to destroy tasks 
created by a PATCH. 

MACID 

Specifies a halfword binary value set to 8 to identify a DPATCH 
service request. 



RC 

Specifies a halfword binary value containing the return code from 
the service request. The return codes are defined in the macro 
description . 



TYPE 

Specifies halfword binary value specifying the DPATCH service 
requests. If 0 is specified, the task is deleted immediately or at 
the completion of the currently executing work request. Any work 
queued to the task is posted as deleted. If 4 is specified, the task 
is deleted only if its work queue is empty. If 8 is specified, the 
task is deleted when the work queue becomes empty. This does not 
prevent new work from being queued. If 12 is specified, the task is 
deleted even if it is active. 



TASK 

Specifies the name of the task being deleted. If left blank, the 
current task is deleted. 



The example assumes the above default structure. The first DPATCH 
request sets up the current task to be deleted when its work queue 
becomes empty. The second DPATCH requests that the task be deleted 
only if it is not doing any work. The last DPATCH requests that the 
task be destroyed regardless of its condition. 



TYPE = 8; 

CALL DPPPIF (DPACHSTR. MACID) ; 

TYPE = 4; 

TASK = 'TESTDPCH*; 

CALL DPPPIF(DPACHSTR .MACID) ; 

TYPE = 12; 

TASK = 'DPCHTEST'; 

CALL DPPPIF( DPACHSTR .MACID) ; 
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MESSAGE Interface 



The MESSAGE service is used to cause a predefined message to be printed 
or displayed. The message must have been defined through the offline 
utility system using the DEFHSG macro. 

The PL/I structure, MESAGSTR, (defined below) contains the parameters 
for the MESSAGE service -and may be copied into the program via %INCLUDE 
MES AGDEF; 



DCL 1 MESAGSTR, 

2 MACID FIXED BIN INIT(40) , 

2 RC FIXED BIN INIT(O) , 

2 MSGNUM FIXED BIN INIT(O) , 

2 ACT CHAR (1 ) INIT (» Mr 

2 WAIT BIT (1) INIT (• O'B) , 

2 RESERVED FIXED BIN(31,0) INIT(O) 

2 AREA POINTER, 

2 ROUTE (8) FIXED BIN INIT (0) , 
2 VAR (10) POINTER; 



/* MESSAGE NUMBER */ 

/* ACTION CODE */ 

/* WAIT = NO */ 

/* RESERVED */ 

/* A (RETURN OF MESSAGE) */ 

/* ROUTING CODES */ 

/* A(VARIABLES) ARRAY */ 



MESAGSTR 

Is the name of the default structure used for the PL/I message 
interface. 



MACID 

Is a halfword binary value of 40' to indicate the service requested 
to the interface routine- 



RC 

Is a halfword binary value containing the return code from the service 
routine. See MESSAGE macro for possible values. 



APPLICATION SERVICES 2-77 



MSGNUM 

Is a halfword binary value from 1 to 999 identifying the message 
requested. 

ACT 

Is a 1-byte character to be appended to the message number. I denotes 
information; A denotes action is required; and D denotes that a 
decision is required. 

WAIT 

Is a flag bit indicating the program's decision to WAIT for the 
message to be sent. Default is off, which is no wait, 

RESERVED 

Is a fullword binary field reserved for the interface routine. 

AREA 

Is a pointer variable containing the address of an area where the 
service routine will place the formatted message for use by the 

program . 

ROUTE 

Specifies a table of 8 halfword binary numbers representing the 
devices on which the message will appear or will be printed. All 
unused entries must be zero. 

VAR 

Specifies a table of 10 pointer variables addressing the variable 
data to be converted and inserted into the message. All unused 
entries must be zero. Only consecutive non-zero entries will be 
used. 

The example below requests the MESSAGE service to output to routing 
code (1) message number 37 with a variable text field of "JOB IS 
FINISHED, PLEASE CANCEL". The message number will have an action code 
of "A" appended to notify the operator to act. The program will wait 
for the message to be transmitted. The example presumes the above 
MESAGSTR structure. 

^INCLUDE MESAGDEF; 



DCL A CHAR(50) 

INIT(»JOB IS FINISHED. PLEASE CANCEL') *. 

DCL X CHAR (128) ; 
MSGNUM = 37; 
ACT = • A « ; 
WAIT = » 1 » B; 
AREA = ADDR (X) ; 
ROUTE (1) = 1 ; 
VAR (1) = ADDR (A) ; 
VAR (2) = NOLL; 

CALL DPPPIF(MESAGSTR-M ACID) ; 



RhAlzMOQEU Interface 

The RECORD facility provides a method for writing data to a sequential 
data set. The data can be retrieved at a later time for offline 
processing. 

The default PL/I structure RECRDSTB, defined below, can be copied into 
the program via a ^INCLUDE BECRDDEF; 
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DCL 1 RECEDSTR, 

2 MACID FIXED BI N INIT (56) , 

2 RC FIXED BIN INIT (0) , 

2 COONT FIXED BIN(31,0) INIT(O), 

2 DATX POINTER, 

2 ID FIXED BIN INIT(O) ; 



/* RECORD ID */ 
/♦ RETURN CODE */ 
/* DATA LENGTH */ 
/♦ DATA ADDRESS ♦/ 
/* DATA ID NO. */ 



RECRDSTR 

Is the name of the default structure used to invoke the RECORD 
service. 



MACID 

Is a halfword binary number used to identify the service being 
requested. Default is 56 for RECORD. 

RC 

Is a halfword binary value containing the completion codo from the 
RECORD service routine. See RECORD macro writeup for valid return 
codes. 



COUNT 

Is a fullword binary number which is the number of bytes to be 
recorded. A maximum value of 6 5535 bytes may be specified. 

DATX 

Is the address of the data to be recorded. 



ID 

Is a halfword binary number from 1 to 4095 which identifies the data 
being recorded. 

The following example presumes the RECRDSTR structiire above: 



DCL A (16) FIXED BIN INIT(5) ; 

COUNT = 32; 

ID = 10; 

DATX = ADDR(A) ; 

CALL DPPPIF (RECRDSTR. MACID) ; 



ELZI PATCH^WAIT Interface 

This interface provides the PL/I programmer the facility to wait for 
the completion of a work queue element generated by a PATCH. The 
following default structure WAITSTR may be copied into a PL/I program 
by a ^INCLUDE WAITDEF. 

DCL 1 WAITSTR, /* PATCH-WAIT STRUCTURE */ 

2 MACID FIXED BIN INIT (60) , /* WAIT MACRO ID ♦/ 

2 RC FIXED BIN INIT(O) , /* ECBPOST CODE */ 

2 EVENT FIXED BIN(31,0) INIT(O); /* ECB */ 

WAITSTR 

Is the name of the default structure provided for waiting on PATCH 
request completion. 

MACID 

Is a halfword binary number of 60 identifying the service requested 
to the interface routine. 

RC 

Is a halfword binary number containing the completion flag byte from 
POST. See PATCH macro for possible values. 
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EVENT 

Is a fullword binary field containing the completion code from the 
finished work queue processing or the address of a BEPATCH control 
block. The value in this field is governed by the contents of RC. 

Note: For this structure, EC will never be zero when the interface 
routine returns to the PL/I program. 

The following example uses the default structures for PATCHsrH and 
MAITSTR as shown. Note, that the user need not zero the variable EVENT 
as the interface routine will automatically zero the first byte when 
moving it to the RC field. 



DCL 1 PATCHPRM, 

2 LENG FIXED BIN, 

2 PATID FIXED BIN, 

2 PARX (10) FIXED BIN(31,0); 

DCL 1 PATCHSTR, 

2 MACID FIXED BIN INIT (0) , 

2 RC FIXED BIN INIT(O) , 

2 PACHPARM POINTER, 

2 TASKNAME CHAR(8) INIT(« •) » 

2 EPNAME CHAR(8) INIT ('lEFBRia*) , 

2 NAME CHAR (8) INIT(» ») , 

2 QUEUE FIXED BIN INIT(1), 

2 VALUE FIXED BIN INIT(O), 

2 ECB POINTER, 

2 FREEL FIXED BIN(31,0) INIT(O), 
2 FREEA FIXED BIN(31,0) INIT(O), 
2 PCBX FIXED BIN (3 1,0) INIT(O), 
2 PFLAGS, 

3 (FO, 

MASTER, 

SLAVE, 

F3, 

REPCH, 

QPOS, 

DPCH, 

DEL) BIT(1) INIT(«0»B); 

DCL 1 WAITSTR, 

2 MACID FIXED BIN INIT (60) , 

2 RC FIXED BIN INIT(O) , 

2 EVENT FIXED BIN (31,0) INIT(O); 

LENG = 4; 
PATID = 2; 

PACHPARM = ADDR (PATCHPFK. LENG) ; 

TASKNAME = 'TESTWAIT* ; 

EPNAME = • WAITTEST' ; 

ECB = ADDR (EVENT) ; 

CALL DPPPIF (PATCHSTR. MACID) ; 

2 EVENT FIXED BIN(31,0) INIT(O); 



PLZI ISZAXCH Interface 

This PL/I interface provides the programmer the facilities of the 
Special Real Time Operating System BEPATCH service. The default 
structure, REPCHSTR (defined below) , may be copied into the PL/I program 
via a 95INCLUDE REPCHDEFj. 
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DCL 1 REPCHSTR, /* REPATCH STROCTURE */ 

2 MACID FIXED BIN INIT(12) , /* REPATCH MACRO ID */ 

2 RC FIXED BIN INIT(O), /* RETURN CODE */ 
2 TYPE FIXED BIN(31,0) INIT(O), /* SERVICE TYPE */ 

2 REPCB FIXED BIN(31,0), /* A(REPATCH CNTL BLK) ♦/ 

2 TASK CHAR (8) r /* TASKNAME */ 

2 EP CHAR (8) /* LOAD MODULE */ 

2 RELTASK CHAR (8), /* REL TASK FOR VALUE */ 

2 QUE FIXED BIN, /* QUEUE LENGTH ♦/ 

2 VAL FIXED BIN, /* PRIORITY CHG */ 

2 ECB POINTER, /* ECB ADDRESS ♦/ 

2 RES (2) POINTER, /* RESERVED ♦/ 

2 TCBX POINTER, /* TCBX ADDRESS */ 

2 PFLAGS, /* FLAG OPTIONS IF BIT IS SET ON ♦/ 

3 (FO, /* RESERVED 

MAST, /* PATCH PARTITION = MASTER ♦/ 

SLAV, /* PATCH PARTITION = SLAVE */ 

F3, /* RESERVED */ 

RPECB, /* ECB REPATCH */ 

QP0S1, /* QPOS=FIRST */ 

DPACH, /* QPOS=DPATCH */ 

DELET) BIT(1), /* EP DELETE */ 

2 RES1 (3) POINTER; /* RESERVED SUPERVISOR POINTERS */ 

REPCHSTR 

Name of the default structure provided for the Special Real Time 
Operating System REPATCH service requests. 

MACID 

A halftford binary value of 12 identifying the service required to 
the interface routine. 

RC 

A half word field containing a binary number return code from the 
REPATCH/PATCH service routine. See REPATCH macro write-up for REPATCH 
and related PATCH return codes. 

TYPE 

A fullword binary value indicating the interface routine service 
required- 

0 — The REPATCH control block is to be copied to the REPCHSTR to 
permit alteration of PATCH parameters prior to REPATCH. 

4 -- Issue REPATCH TYPE=EXEC. 

8 — Issue REPATCH TYPE=PURGE. 

REPCB 

A fullword binary field to contain the REPATCH control block address 
placed in the W AITSTR . E VENT when WAITSTR, RC equaled 68. The value 
in EVENT must be moved to REPCB before any interface call except the 
first interface call TYPE='4 or 8 following a TYPE=0 interface call. 

TASK 

Specifies an 8-character name which is the name of the task being 
referenced by this PATCH. 

EP 

Specifies the 8-character valid program name of the program to be 
scheduled under the task specified in TASK. 

RELTASK and VAL 

Specifies an 8-character task name and a halfword value which will 
determine the priority of the new task. VAL will be subtracted from 



APPLICATION SERVICES 2-81 



the dispatching priority of the specified task. VAL may range fron 
0 to 255 with zero default. See PRTY option of PATCH macro for 
further detail. 

QUE 

A half word value specifying the number of wprk queue entries to be 
provided for a new independent task. 

ECB 

Specifies the address of the ECB within a WAITSTR which is to be used 
in a CALL DPPPIF. This ECB is posted when processing for this PATCH 
completes. The ECB which contained the REPATCH control block address 
may be reused a Ad will be if this parameter is left unchanged. 

TCBX 

Specifies the address of the TCB extension control block for an 
existing independent task. 

PFLAGS 

The PATCH option flags as described below: 
MAST 

This PATCH is intended for the MASTER partition. 
SLAV 

This PATCH is intended for the SLAVE partition. 

RPECB 

Specifies that if this work request is pushed off the queue, the 
ECB is to be posted with a REPATCH control block address. 

QP0S1 and DPACH 

Specifies where in the task work queue this work request is to go 
if the task is busy. If QP0S1 is on, the request is to be placed 
first on the queue. If DPACH is on, the processing for this PATCH 
will not be executed until a DEPATCH is issued for this task* Both 
flhgs off means this request is queued last. 

DELET 

Specifies that a DELETE is issued for the EP name after processing 
completes for this PATCH. 

RES and RES1 
The pointers must remain unchanged. 

The Special Real Time Operating System REPATCH service may be invoked 
by including the REPCHDEF in the PL/I program, moving the REPATCH 
control block address from the event control block to REPCB and then 
executing one of the following: 

a. If the REPATCH is to be done without change, set TYPE to 4 or 8 
and CALL DPPPIF. 

b. If the REPATCH is to be changed prior to execution, set TYPE to 0, 
CALL DPPPIF, make changes desired, set TYPE to 4 and CALL DPPPIF 
again. 

Users of this facility should be aware that only the "supervisor" 
portion of the PATCH parameters can be altered. The problem parameters 
cannot be changed. All REPATCH control blocks must be returned to the 
system through a TYPE=4 or 8 service request. 
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The following examples will show the various methods of using REPCHSTR. 



The examples for using the REPCHSTR use the following set of structures: 



1 


REPCHSTR , 


/* 


REPATCH STRUCTURE */ 


2 


HACID FIXED BIN INIT(12) , 




REPATCH MACRO ID */ 


2 


RC FIXED BIN INIT tO^ . 


/* 


RETURN CODE */ 


2 


TYPE FIXED BIN(31,0) INIT(0)r 




SERVICE TYPE */ 


2 


REPCB FIXED BIN(31,0), 


/* 

r 


A (REPATCH CNTL BLK) */ 


2 


TASK CH AR (8 ) , 


/ 


TASKNAME */ 


2 


EP CHAR (8) , 


f 


LOAD MODULE */ 


2 


RELT ASK CHAR (8) , 


/* 


REL TASK FOR VALUE */ 


2 


QUE FIXED BIN, 


/ 


QUEUE LENGTH */ 


2 


VAL FIXED BIN, 


/* 


PRIORITY CHG */ 


2 


ECB POINTER, 




ECB ADDRESS */ 


2 


RES (2) POINTER, 




RESERVED */ 


2 


TCBX POINTER, 


f 


TCBX ADDRESS */ 


2 


PFLAGS , 




FLAG OPTIONS IF BIT IS SET ON 




3 fFO - 


f 


RESERVED */ 




W AST, 


/* 


PATCH PARTITION = MASTER ♦/ 




SLAV, 


/* 


PATCH PARTITION = SLAVE ♦/ 




F3, 


/* 


RESERVED */ 




RPECB, 


/♦ 


ECB REPATCH */ 




QP0S1 , 


/* 


QPOS=FIRST */ 




DPACH, 


/* 


QPOS=DPATCH */ 




DELET) BIT(1) , 


/* 


EP DELETE */ 


2 


RES1 (3) POINTER; 


/* 


RESERVED SUPERVISOR POINTERS * 


1 


WAITSTR, 


/* 


PATCH-WAIT STRUCTURE */ 


2 


MACID FIXED BIN INIT (60) , 


/* 


WAIT MACRO ID */ 


2 


RC FIXED BIN INIT (0) , 


/* 


ECB POST CODE */ 



2 EVENT FIXED BIN(31,0) INIT(O); /* ECB */ 



EXAMPLE 1 : Example 1 shows the correct method for purging a REPATCH 
control block, should a work request fail to be executed. The example 
begins with the PATCH-WAIT which is notified about the work request 
not getting done. 



CALL DPPPIF (WAITSTR, MACID) ; 
IF WAITSTR-RC = 68 THEN DO; 

REPCHSTR. REPCB = W AITSTR . E VENT ; 

REPCHSTR. TYPE = 8; 

CALL DPPPIF (REPCHSTR, MACID) ; 
END; 

Example 1 
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EXAMPLE 2: Example 2 demonstrates the method for altering a REPATCH 
control block. As with Example 1, this example begins vith a WAIT on 
a PATCH. 



X: CALL DPPPIF (WAITSTR. MACID) ; 
IF WAITSTR. RC = 68 THEN DO; 

REPCHSTR.REPCB = WAITSTR-E VENT ; 

REPCHSTR.TYPE = 0; 

CALL DPPPIF (REPCHSTR. MACID) ; 

REPCHSTR.PFLAGS..QP0S1 = M'B; 

WAITSTR. EVENT = 0; 

REPCHSTR.TYPE = H; 

CALL DPPPIF (REPCHSTR. MACID) ; 

IF REPCHSTR. RC <8 THEN GOTO X; 
END; 



Example 2 

The above example replaces the work request on the work queue for the 
same task as previously requested, except that it will be placed first 
on the queue. 



EltZI GETARRAY^UTARRAY In terf ace 

This PL/I interface provides the programmer the facilities of the 
Special Real Time Operating System GETARRAY and PUTARRAY services- The 
default structure, ARRAYSTR (defined below) , may be copied into the 
PL/I program via a ?5INCLUDE ABRAYDEF;. 

DCL 1 ARRAYSTR, /* GET/POT ARRAY STRUCTURE */ 

2 MACID FIXED BIN INIT(16) , /* ARRAY MACRO ID */ 

2 RC FIXED BIN INIT(O) , /* RETURN CODE */ 

2 NAME POINTER, /* A (NAMELIST/NUMBERLIST/ADDRLIST) 

2 AREA POINTER, /* A (FINDLIST/DATAAREALIST) */ 

2 NAMEINCR FIXED BIN INIT(O), /* LIST INCREMENT */ 

2 AREAINCR FIXED BIN INIT(O) , /* LIST INCREMENT */ 

2 TYPE FIXED BIN INIT(O); /* TYPE OF ARRAY SERVICE */ 

ARRAYSTR 

Name of the default structure provided for the Special Real Time 
Operating System array service requests. 

MACID 

A halfword binary value of 16 identifying the service required to 
the interface routine. 



RC 

A halfword field containing a binary number return code from the 

array service routine. See GETARRAY and PUTARRAY macro write-ups 
for possible values. 

NAME 

The address of one of the following based on the specifications 
imjilied by the value of TYPE, 

a. If TYPE specifies 'NAMELIST*, then NAME points to a list of 

8- character array names followed by an X'FF* after the last name 
where the next name would start. NAMEINCR contains the value 
to be added to the list address to locate the next array name. 
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NAMF LIS'I' 



NAMF. 



namf:2 



b. If TYPE specifies • NU MBERL 1ST ' , then NAME points to a list of 
halfword binary array numbers followed by an X*FF' after the 
last array number where the next number would start. NAHEINCR 
contains the value to be added to the list address to locate 
the next array number in the list. 



NUMBFR LIST 



0 1st number 

2 2ndnumbf:r 



c. If TYPE specifies • ADDRESSLIST • , then NAME points to a list of 
array addresses as returned from a previous GETAFRAY execution. 
The list must be terminated by a fullword binary value of -1 
after the last array address where the next address would be 
located. NAMEINCR contains the value to be added to the List 
address to locate the next array address. 



ADDRESS LIST 



0 A( LS I' ARRAY) 



4 A(2ND ARRAY) 



8 ITFFFFFF 



AREA 

The address of one of the following based on the specifications 
implied by the value of TYPE. 

a. If TYPE specifies 'DATALIST' , then AREA points to a list of 

addresses into or from which the data of the specified arrays 
(see NAME above) is to be moved. AREAINCP contains the value 
to be added to the list address to locate the next data area 
address in the list. 



DA I A ARl A ADDRf SS LIST 



0 AdST DA LA ARF.A) 



4 A(2ND DA TA ARFA) 



X A(3RD DAT A ARI A) 



b. If TYPE specifies 'FINDLIST', then AREA points to a list of 

10-byte fields to be filled with a flag byte (see GETARRAY macro 
write-up), a 3-byte array address, a halfword block count, a 
halfword array size or block size and a halfword item count. 
The list must contain one entry more than the number of addresses 
expected to allow for an end of list X*FF». AREAINCP contains 
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the value to be added to the list address to locate the next 
10-byte field. The minimum value for AREAINCR under this option 
is 8; in which case, the item count ha If word will not be in the 
list . 



FIND LIST 



0 


FLG 


ARRAY ADDR 


NO.BLKS 


SIZE 


NO.ITEMS 


10 


FLG 


ARRAY ADDR 


NO.BLKS 


SIZE 


NO.ITEMS 


20 


FF 











c. If TYPE specifies 'SPECLIST', then AREA points to a list of 

16-byte fields to be filled with an 8-byte item name, a 1-byte 
item length, a 1-byte data type, a half word array displacement 
to the start of the item, a halfword array ID, and a halfword 
number identifying the number of identical and sequential items 
defined by this entry. AREAINCR contains the value to be added 
to the list address to locate the next 16-byte field. 



ARRAY SPECIFICATIONS LIST 



0 


ITEM NAME 


LNG 


TYPE 


DISP. 


AID 


REPT 


16 


ITEM NAME 


LNG 


TYPE 


DISP 


AID 


REPT 


32 


ITEM NAME 


LNG 


TYPE 


DISP 


AID 


REPT 



NAMEINCR 

A halfword value added to NAME to locate the next entry in the list. 
A value must be specified. 

AREAINCR 

A halfword value added to AREA to locate the next entry in the list. 
A value must be specified. 

TYPE 

A halfword binary value specifying the array service options selected 
The values (given in the tables below) identify the contents of NAME 
and AREA, either a GETARRAY or PUTARRAY, the array service (i.e., 
DATALIST, ADDRLIST or SPECLIST) , and the desired protection for 
GETARRAYs (PROTECT or RISK) . 

DATALIST 

Specifies that the content of the array (s) is to be returned 
(GETARRAY) or updated (PUTARRAY). 

ADDRLIST 

Specifies that a 'FINDLIST' entry is to be completed for each array 
name or number in the list. Option is valid for virtual storage 
resident arrays only. 

SPECLIST 

Specifies that a 'SPECLIST' entry is to be completed for each item 
of each array name or number in the list. 

PROTECT 

Specifies that the array service will lock daring processing to 
prevent changes from altering results. 
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RISK 

Specifies that the array service will be processed regardless of the 
possibility of parallel processing changing the array content. 



NAME 


AREA 


ot-K Vict 

REQUESTED 


rKU 1 llL. I IL/IN 

REQUESTED 


1 I rC, 

VALUE 


A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


16 


A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


17 


A(NAME LIST) 


A(SPEC LIST) 


SPECLIST 


PROTECT 


20 


A(NAMELIST) 


A(SPEC LIST) 


SPECLIST 


RISK 


21 


A(NAME LIST) 


A(FIND LIST) 


ADDR LIST 


PROTECT 


34 


A(NAME LIST) 


A(FIND LIST) 


ADDR LIST 


RISK 


35 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


48 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


49 


A(NUMBER LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


80 


A(NUMBER LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


81 


A(NUMBER LIST) 


A(SPEC LIST) 


SPECLIST 


PROTECT 


84 


A(NUMBER LIST) 


A(SPEC LIST) 


SPECLIST 


RISK 


85 


A(NUMBER LIST) 


A(F1ND LIST) 


ADDR LIST 


PROTECT 


98 


A(NUMBER LIST) 


A(FIND LIST) 


ADDR LIST 


RISK 


99 


Figure 2- 15. 


GETTARRAY Services 






A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


128 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


144 


A(NUMBER LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


176 


Figure 2-16, 


POTARRAY Services 







The GETARRAY/PUTARRAY services are invoked in PL/I by CALLing DPPPIF 
with the properly completed array narae/number/address list data address 
list and structure (ARRAYSTR or a similar structure). 

The examples for using GETARRAY or POTARRAY services in PL/I use the 
following list of structures and variables: 
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DCL 1 AERAYSTR, 

2 MACID FIXED BIN INIT(16), 
2 RC FIXED BIN INIT(O) , 
2 NAME POINTER, 
2 AREA POINTER, 

2 NAMEINCR FIXED BIN INIT(O) , 
2 AREAINCR FIXED BIN INIT(O) , 
2 TYPE FIXED BIN INIT(O); 
DCL 1 ARRAY, 

2 NAME (2) CHAR (8), NO (2) FIXED BIN, 

2 FIND 02) , 

3 ADDRESS POINTER, 

3 BLKCNT FIXED BIN, 

3 BLKSIZ FIXED BIN, 

3 ITEMCNT FIXED BIN, 

3 RES FIXED BIN, 

2 CORE (2) POINTER; 
DCL 1 ARRAYITM (255) , 

2 NAME CHAR (8) , 

2 LNG BIT (8) , 

2 TYP BIT(8) , 

2 DISP FIXED BIN; 
DCL ITEM (2 55) CHAR (1 6) ; 
DCL Q POINTER BASED (P); 



Note, that the structure ARRAY has the field NAME for use when calling 
arrays by name, or NO for use when calling arrays by number. 

Both of the following examples make use of the fact that once a 
structure has been altered it remains unchanged; i.e., the array name 
in the first example needed to be specified only once. 

The first example will locate array » B* through the FINDLIST option, 
r'jad in the item specifications through the SPEC option and then read 
in the array. The array is then changed and the new array transmitted. 



ARR AY. NAHE( 1) = » B • ; /♦ 
P = ADDR{ ARRAY, NAME(2) ) ; /* 
Q = NULL; /* 
ARR AYSTR. NAME = ADDR ( ARR AY. NAME (1 ) ) ; 
ARR AYSTR. NAMEINCR = 8; 

ARRAYSTR. AREA = ADDR (ARRAY. FI ND (1 ). ADDRESS) ; 

ARRAYSTR. AREAINCR = 12; 

ARRAYSTR- TYPE = 35; 

CALL DPPPIF (ARRAYSTR. MACID) ; 
/♦ THE FIND LIST HAS BEEN BUILT */ 

ARRAY. COR E(1) = ADDR (ARR AYITM (1) . NAME) ; /* 

ARRAYSTR. AREAINCR = U; /* 

ARRAYSTR- AREA = A DDR ( ARR A Yi CORE < 1 ) ) ; /♦ 

ARRAYSTR. TYPE = 21; /* 

CALL DPPPIF (ARRAYSTR. MACID) ; 
/* THE ITEM SPECIFICATIONS HAVE BEEN OBTAINED */ 

ARRAY. C0RE(1) = ADDR (ITEM ( 1) ) ; /* 

ARRAYSTR. TYPE = 16; /* 

CALL DPPPIF (ARRAYSTR- MACID) ; 
/* THE ARRAY HAS BEEN READ */ 

ITEM(1) = 'THIS BLOCK ZAPED'; 
THE ARRAY IS ALTERED */ 

ARRAYSTR. TYPE = 128; /♦ 

CALL DPPPIF (ARRAYSTR. MACID) ; 
/* THE ARRAY IS UPDATED */ 



BOILD PARAMETER */ 
LIST TO LOCATE */ 
NAMED ARRAY */ 



BOILD PARAMETER */ 
LIST TO */ 
OBTAIN */ 

LIST OF ITEM NAMES */ 



READ THE */ 
ENTIRE ARRAY */ 



RRITE THE ENTIRE ARRAY 



Example 1 



Note that in the above example all services to the array are by name. 
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The second example is identical to the first, except that the array i 
numbered. 

ARRAY. N0(1) = 1; 
ARRAY. NO (2) = -l.- 
ARR AY STR . NAME = ADDR (ARRAY, NO (1) ) ; 
ARRAYSTR, NAMEINCR = 2; 

ARRAYSTR. AREA = ADDR (ARRAY, FI ND (1 ). ADDRESS) ; 

ARRAYSTR. AREAINCR = 12; 

ARRAYSTR. TYPE = 99; 

CALL DPPPIF (ARRAYSTR. MACID) ; 
/* THE FINDLIST HAS BEEN BUILT */ 

ARRAY. C0RE(1) = ADDR ( ARR AYI TM (1 )- NAME) ; 

ARRAYSTR. AREA = ADDR (ARRAY- CORE (1 )) ; 

ARRAYSTR. AREAINCR = 4; 

ARRAYSTR. TYPE = 85; 

CALL DPPPIF (ARRAYSTR. MACID) ; 
/* THE ITEM SPECIFICATIONS HAVE BEEN OBTAINED */ 

ARRAY. C0RE(1) = A DDR (ITEM (1 ) ) ; 

ARRAYSTR. NAME = A DDR ( ARR A Y- FI ND ( 1 ) . ADDRES S) ; 

ARRAY. FIND(2) .ADDRESS = NOLL; 

/ARRAYSTR. NAMEINCR = 12; 

ARR AYSTR. TYPE = U8; 

CALL DPPPIF (ARRAYSTR- MACID) ; 
/* THE ARRAY HAS BEEN READ */ 

ITEH(1) = 'THIS BLOCK ZAPED'; 
/* THE ARRAY IS ALTERED ♦/ 
ARRAYSTR. TYPE = 144; 

CALL DPPPIF (ARRAYSTR- MACID) ; 
/* THE ARRAY HAS BEEN UPDATED */ 

Example 2 



Note, that the array was read and written using the ADDR option. 



IIZI GETITEM/PUTITEM Interface 

This PL/I interface provides the programmer the facilities of the 
Special Real Time Operating System GETITEM and PUTITEM services. The 
default structure, ITEHSTR (defined below) , may be copied into the PL 
program via a %INCLODE ITEMDEF;. 



DCL 1 ITEMSTR, 

2 MACID FIXED BIN INIT (20) , 

2 RC FIXED BIN INIT(O), 

2 NAME POINTER, 

2 AREA POINTER, 

2 NAMEINCR FIXED BIN INIT(O), 

2 AREAINCR FIXED BIN INIT(O) , 

2 TYPE FIXED BIN INIT(O); 



/♦ GET/PDT ITEM STRDCTURE ♦/ 

/* ITEM MACRO ID */ 

/* RETURN CODE */ 

/* A (NAMELIST/ADDRLIST) */ 

/* A (DAT A AREA) */ 

/♦ LIST INCREMENT */ 

/* LIST INCREMENT ♦/ 

/* TYPE OF ITEM SERVICE V 



ITEMSTR 

Name of the default structure provided for the Special Real Time 
Operating System array- item service requests. 

MACID 

A halfword binary value of 20 identifying the service required to 
the interface routine. 
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PC 

A halfword field containing a binary number return cods from the item 
service routine. See GETITEM and POT ITEM macro write-ups for possible 
values. 

NAME 

The address of one of the following based on the specifications 
implied by the value of TYPE. 

a. If TYPE specifies 'NAMELIST* , then NAME points to a list of 

8-character item names followed by a X • FF' after the last name 
where the next name would start. NAMEINCR contains the value 
to be addsd to the list address to locate the next item name. 



NAME LIST 



NAME I 



NAME 2 



r F 



b. If TYPE specifies 'ADDRESS LIST» , then NAME points to a list of 
item addresses as returned from a previous execution. The list 
must be terminated by a fullword of -1 where the next address 
would be in the list. NAMEINCR contains the value to be added 
to the list address to locate the next address in the list. 



ADDRESS LIS! 



0 A(lTFMa) 



4 Ad TFM b) 



AREA 

the address of one of the following based on the specifications 
implied by the value of TYPE. 

a. If TYPE specifies 'DATALIST*, then AREA points to a data area 
into or from which item data is moved. AREAINCR contains the 
value to be added to the area address to locate the next area 
for the next item. If AREAINCR is zero, then the item length 
is used to determine the location for the next item data area. 

b. If TYPE specifies 'ADDRLIST', then AREA points to a list of 
U-byte entries into which .the item length and address are stored 
for each item specified in the 'NAHELIST*. The list must be 
one entry longer than the number of addresses being obtained to 
allow the service routine to store an end of list X'FF'. 
AREAINCR contains the value to be addad to the area address to 
locate the next entry. 



ADDRESS LIST 



ITEM 
LENGTH 


ITEM ADDRESS 


ITEM 
LENGTH 


ITEM ADDRESS 


F- F 


F F F F F F 
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c. If TYPE specifies 'SPECLIST' , then AREA points to a list of 
4-byte entries containing the item length, flags identifying 
data type and a displacement into the array to the first byte 
of the item, AREAINCR contains the value to be added to the 
area address to locate the next entry. 



ITEM SPECIFICATIONS LIST 



ITEM 
LENGTH 


TYPE FLAGS 


ARRAY DISPLACEMENT 


ITEM 
LENGTH 


TYPE FLAGS 


ARRAY DISPLACEMENT 


ITEM 
LENGTH 


TYPE FLAGS 


ARRAY DISPLACEMENT 



NAMEINCR 

A halfword binary value added to the list address in NAME to locate 
the next entry. A value must be specified. 

AREAINCR 

A halfword binary value added to the list address in AREA to locate 

the next entry. A value must be specified unless TYPE specifies 

'DATALIST' in which case %ero may be used. 

TYPE 

A halfword binary number specifying the item service options selected. 
The values (given in the tables below) identify the kind of service 
(i.e., DATA, ADDR or SPEC), and whether it is a GETITEM with or 
without protection (PROTECT or RISK) or a PUTITEM. 

DATALIST 

Specifies that the content of the array-item is to be moved from the 
array to AREA or updated by the contents of AREA. 

ADDRLIST 

Specifies that the item • ADDRES SLIST* is to be built in AREA for each 
named item. 

SPECLIST 

Specifies that the item 'SPECIFICATION LIST' is to be built in AREA 
for each named item- 
PR OTECT 

Specifies that the GETITEM service will ensure data integrity during 
processing, 

RISK 

Specifies that the GETITEM service will process the request regardless 
of the possibility of parallel processing updating the content of 
the named item(s). 

Note: DATALIST and DDDRLIST are invalid service requests for direct 
access resident arrays. 



APPLICATION SERVICES 2-91 



NAME 


AREA 


SERVICE 


PROTECTION 


TYPE 

VAT 1 IP 


AWAME LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


136 


A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


137 


A(NAME LIST) 


A(ADDR LIST) 


ADDR LIST 


PROTECT 


138 


A(NAME LIST) 


A(ADDR LIST) 


ADDR LIST 


RISK 


139 


A(NAME LIST) 


A(SPEC LIST) 


SPEC LIST 


PROTECT 


140 


A(NAME LIST) 


A(SPEC LIST) 


SPEC LIST 


RISK 


141 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


152 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


153 



Figure 2-17. GETITEM Services 



A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


184 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


200 



Figure 2-18. PUTITEM Services 



The GET IT EM /PUT ITEM services are invoked in PL/I by CALLing DPPPIF wi 
the properly completed item name/ address list, data address list and 
structure (ITEMSTR or a similar structure). 

The example for using GETITEM or PDTITEM services in PL/I uses the 
following list of structures and variables: 



DCL 1 ITEMSTR, 

2 MACID FIXED BIN INIT(20), 
2 EC FIXED BIN INIT (0) , 
2 NAME POINTER, 
2 AREA POINTER, 
2 NAMEINCR FIXED BIN INIT(O) 
2 AREAINCR FIXED BIN INIT(O) 
2 TYPE FIXED BIN INTT(O) ; 
DCL 1 ITEMLIST (6) , 

2 NAME CHAR ( 8) , 
2 ADR POINTER, 
2 LNG BIT(8) , 
2 FLGS BIT (8) , 
2 DISP FIXED BIN; 
HAR( 16) : 

BASED (P) ; 
BASED(PT) ; 



DCL ITEM (5) C 
DCL Q POINTER 
DCL F BIT (8) 



The following example will use GETITEM services to obtain the address 
specifications and data for a list of five items from the same array. 
It will change the data and use PUTITEM services to update the array. 
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ITEHLIST(I) .KAHB = •B01 
ITEHLIST(2) .HKHE = 'B03 
ITBHLIST(3) .NAME = 'BOS 
ITEnLlST(4) .HAHB «= 'BO? 
ITEHLIST(5) .MAHE = 'BOS 
P = ADDR(ITEMLIST (6) . MAME) ; 
Q = NOLL; 

ITEBSTR.IIAHE = ADDB (ITEHLIST (1) . M ARE) ; 
ITEHSTR.NAHEIHCR = 16; 

ITEHSTR.AREA = ADDH (ITE HLIST ( 1) - ADR) ; 
ITEHSTR. AREAINCR = 16; 
ITEBSTR.TYPE = 136; 
CALL DPPPIP (ITE BSTH.H ACID) ; 
/* ITEB ADDRESSES ARE HBSOL?ED */ 
DO I = 1 TO 5; 
PT = ADDR (ITEHLIST(I) . ADH) ; 
F = 'OOOOOOOO'B; 
END; 

/* PREPARE PARB LIST TO GET ITEB SPECS */ 

ITEMSTR.AREA - ADDR (ITE RLIST ( 1) . LNG) ; 

ITEBSTR.TTPB = 138; 

CALL DPPPIP (ITEBSTR.BACID) ; 
/* ITEB SPECIPICATIOHS OBTAINED ♦/ 

ITBBSTR.NABE = ADDR (ITBBLIST ( 1) . ADR) ; 

ITEBLIST(6) .ADR « NOLL; 

ITEBSTR.AREA = ADDR (ITEB ( 1) ) ; 

ITEBSTR. ARBAINCR = 16; 

ITBBSTH.TIPE * 158; 

CALL DPPPIP (ITEBSTR.BACID) ; 
/* DATA HAS BEEN BEAD V 

DO I = 1 TO 5; 

ITEB (I) = 'THIS BLOCKS GONE'; 
END; 

/♦ WRITE ARRAY UPDATES BY ADDRESS ♦/ 

ITEBSTR.TYPE = 200; 

CALL DPPPIP (ITEBSTR.BACID) ; 
/♦ OPDATB IS COBPLETE ♦/ 



/* 



/* 
/* 
/* 



BOILD LIST OP */ 
ITEB NABES ♦/ 



TERBINATB LIST ♦/ 
BOILD PARB LIST ♦/ 
TO LOCATE ITEBS */ 



ZERO OPPER BYTE */ 
OP ADDRESS iORDS */ 



BOILD */ 

PARAMETER LIST */ 
TO READ V 
BY ADDRESS */ 



/* ALTER DATA */ 



PL/I GETB LOCK/PUT BLOCK In terf ace 



This PL/I interface provides the programaer the facilities of the 
Special Real Tiie Operating System GETBLOCK and PUTBLOCK s^ervices. The 
default structure, BLOCKSTR (defined below) , may be copied into the 
PL/I program via a %INCLODE BLOCKDEP. 



DCL 1 BLOCKSTR, 

2 WACID PIIED BIN INIT ( 24), 

2 RC PIXBD BIN INIT(O) , 

2 NAME POINTER, 

2 AREA POINTER, 

2 ADD FIXED BIN INIT (8), 

2 TYPE FIXED BIN INIT(4); 



/* GET/POT BLOCK STROCTORE */ 

/* BLOCK flACRO ID */ 

/* RETURN CODE */ 

/* A INAMELIST/NUMBEFLIST) */ 

/• A (DATA ADDR-BLK NO. LIST) */ 

/* DATA AREA INCREMENT */ 

/* TYPE OF BLOCK SERVICE ♦/ 



BLOCKSTR 

Name of the default structure provided for the Special Real Time 
Operating System blocked arrays service requests. 

BACID 

A half word binary value of 24 identifying the siervice required to 
the interface routine. 



RC 

A halfword field containing a binary number return code from the 
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blocked array service routine. See GETBLOCK and POTBLDCK nacro 
write-ups for possible values. 

HA ME 

The address of one of the following based on the specifications 
implied by TYPE, 

a. If TYPE specifies 'NAME LIST', then NAME points to a list of 
8-character array names followed by a X'FP' in the first byte 
after the last name where the next name would start. 



ARRAY NAME LIST 



NAME 



NAME 



16 



F F 



b. If TYPE specifies •NUMBER LIST', then NAHE points to a list of 
halfword (2-byte) binary array numbers followed by a X*PP« in 
the first byte after the last number where the next number would 
start. 



NUMBER LIST 



0 NUMBER 
2 NUMBER 
4 FF 



AREA 

The address of a list of 6-byte entries. ADD contains the value to 
be added to the list address to locate the next entry. 



DATA AREA LIST 



FLG 


DATA AREA 


BLK. NO 


FLG 


DATA AREA 


BLK. NO. 


FLG 


DATA AREA 


BLK. NO. 



FLG 

A 1-byte flag field. A X»40« indicates the last data area and block 
number for a specified array, but not the end of the list. A X»8D» 
indicates the last entry for the last array and the end of the list. 
A X*00» should appear in all other entries. 

DATA AREA 

A 3-byte address of the area into or from which the specified array 
block is moved. 

BLK. :^o. 

A halfword binary number specifying the array block being moved. 
ADD 

A halfword binary value added to the contents of AREA to locate the 
next entry in tha list. If zero, a length of 6 is assumed. 



2-94 



Description and Operation Hanual 



TYPE 

A halfword binary value specifying the blocked array service options 
selected. The values (given in the tables below) identify the 
contents of NAME and whether it is a GETBLOCK with or without 
protection (PROTECT or RISK) or a PUTBLOCK. 



NAME 


AREA 


PROTECTION 
REQUESTED 


TYPE 
VALUE 


A(NAME LIST) 
A(NUMBER LIST 

A(NAME LIST) 
A(NUMBER LIST) 


A(DATA LIST) 
A(DATA LIST) 
A(DATA LIST) 
ACDATA LIST) 


RISK 

RISK 
PROTECT 
PROTECT 


4 
6 
12 
14 


Figure 2-19. 


GETBLOCK Services 




A(NAME LIST) 
A(NUMBER LIST) 


A(DATA LIST) 
A(DATA LIST) 


N/A 
N/A 


5 



Figure 2-20. PUTBLOCK Services 



The GETBLOCK/PUTBLOCK services are invoked in PL/I by CALLing DPPPIF 
with the properly completed structure (BLOCKSTR or a similar structure) 
the array name or number list and data address list. 
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The following example will GETBLOCK for block 5 from the two arrays 
BLK1 and BLOKB, and PUTBLOCK the block 5 of array BLK1 to block 5 of 
array BLOKB. 

DCL 1 BLOCKSTR, 

2 MACin FIXED BIN INIT (2U) , 

2 RC FIXED BIN INIT(O) , 

2 NAME POINTER, 

2 AREA POINTER, 

2 ADD FIXED BIN INIT (8) , 

2 TYPE FIXED BIN I NIT (4) ; 
DCL 1 BLK, 

2 NAME (2) CHAR(8) , 

2 NO (2) FIXED BIN, 

2 LIST (2) , 

3 AREA POINTER, 
3 NOM FIXED BIN, 
3 RES FIXED BIN; 
DCL BLOCK (2) CHAR (256); 
DCL Q POINTER BASED (P); 
DCL F BIT (8) BASED (PT); 
BLK.NAME(I) = » BLKI ' ; 
BLK.NAME(2) = 'BLOKB '; 
BLK.NO(I) ^ -1; 

BLK,LIST(1) . ARE A = ADDR (BLOCK ( 1 )) ; 

PT = ADDR (BLK.LIST(1) .AREA) ; 

F = 'OlOOOOOO'B; 

BLK-LIST(I) .NUM = 5 ; 

BLK.LIST(2) , ARE A = ADDR (BLOCK (2 )) ; 

PT = ADDR (BLK. LIST (2) , AREA) ; 

F = « 10000000' ; 

BLK.LIST(2) .NUM ^ 5 ; 

BLOCKSTR. NAME = A DDR (BLK- NA ME ( 1 ) ) ; 
BLOCKSTR. AREA = A DDR (BLK. LIST (1 ) ,. AR EA) ; 
BLOCKSTR. TYPE = 12; 
CALL DPPPIF (BLOCKSTR, MACID) ; 
/* BLOCK 5 ARRAYS BLKI AND BLOKB HAVE BEEN READ */ 
BLK-NAME(I) = BLK.NAME(2); 
P = ADDR(BLK. NAME (2) ) ; 
Q = NULL; 

PT = ADDR (BLK. LIST(1) . AREA) ; 
F = » 10000000'B; 
BLOCKSTR. TYPE = 5; 
CALL DPPPIF (BLOCKSTR- MACID) ; 
/* BLOCK 5 OF ARRAY BLKI HAS BEEN WRITTEN TO 
BLOCK 5 OF ARRAY BLOKB */ 



PLZIrGETLOG I nter fa ce 

This PL/I interface provides the programmer the facilities of the GETLOG 
service. The default structure (defined below) may be copied into the 
PL/I program via a %INCLUDE GTLOGDEF; . 
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DCL 1 



GTLOGSTR, 

MACID FIXED BIN INIT(U8), 
PC FIXED BIN INIT(O) , 
TYPE, 

3 (F0,F1, 

LOGHDR , 

F3, 

PROTECT, 
F5, 

NOMBER , 

F7) BIT (1) INIT (' 0« B) , 
RES BIT (1) INIT (• 0* B) , 
NO FIXED BIN, 
AREA POINTER, 

STEP FIXED BIN(31,0) INIT(o), 
HEAD POINTER, 
NAME POINTER; 



/* 
/* 
/* 

/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/♦ 
/* 
/* 



GETLOG DEFAULT STROCTaRE */ 
GETLOG MACRO ID */ 
RETURN CODE */ 
PARAMETER LIST FLAGS V 
RESERVED */ 

A(LOGHEADER) IN HEAD */ 
RESERVED */ 

ON IF PROTECTION REQ»D */ 

RESERVED */ 

NUMBERED ARRAY */ 

RESERVED */ 

RESERVED */ 

ARRAY NUMBER */ 

DATA ARFA */ 

RELATIVE COPY NO */ 

A (LOGHEADER/TIME FIELD) */ 

A (ARRAY NAME) */ 



2 
2 
2 



2 
2 
2 
2 
2 
2 



GTLOGSTR 

Name of the default structure provided for the Special Real Time 
Operating System GETLOG service requests. 

MACID 

A halfword binary value of HQ identifying the requested service to 
the interface routine. 

RC 

A halfword binary field containing a binary number return code from 
the GETLOG service routine. See GETLOG macro write-up for possible 
val ues. 

TYPE 

A flag's field indicating to the GETLOG se*:vice routine the options 
requested. 

LOGHDR 

If on, HEAD contains the address of a 24-byte log header identifying 
the relative starting point to determine which copy of the array will 
be retrieved from the log data set. 

If off and HEAD is zero, the current copy becomes the relative 
starting point. If off and HEAD is not zero, then it contains the 
address of a 6-byte time and day field beginning on a fullword 
boundary. The first four bytes will contain a time in 10 millisecond 
units. The last two bytes will contain a binary value from 1 to 366 
representing the day of the year. This time and day will be used as 
a comparison value to establish a relative starting point to determine 
which copy of the array fill be retrieved from the log data set. 

PROTECT 

If on, a lock is set to prevent other programs from modifying the 
data set while this GETLOG is in process. If off, the data is moved 
without regard to other programs which may be storing into the data 
set. 

NUMBER 

If on, specifies that NO contains an array number- If off, NAME 
contains the address of an 8-character array name padded on the right 
with blanlcs if needed. 

NO 

Specifies the number of a numbered array for which a logged copy of 
the array is to be retrieved. 
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AREA 

Specifies the address of a user-allocated storage area where the 
logged copy of the array will be written upon retrieval from the log 
data set. This area must be large enough to hold the entire array 
and a logheader (24 bytes) - 

STEP 

Is used to determine which copy of a logged array, relative to the 
HEAD parameter will be retrieved from the log data set. The value 
is a signed number which may be either positive, negative, or zero. 

HEAD 

Zero or the address of an array logging header or of a 6-byte time 
and day field. See LOGHDR, under TYPE above for discussion of the 
contents of HEAD. 



NAME 

The address of the name of a named array for which a logged copy of 
the array is to be retrieved. 

The GETLOG service is invoked in PL/I by CALLing DPPPIF with a properly 
completed GTLOGSTR or a similar structure. 

The following example will execute a GETLOG for the previously logged 
copy of array B referenced from the current copy. Note that the 
structure into which the log copy is read provides space for the log 
h eader. 



DCL 1 GTLOGSTR, 

2 MACID FIXED BIN INIT(48), 
2 RC FIXED BIN INIT(O) , 
2 TYPE, 

3 (F0,F1, 

LOGHDR . 

F3, 

PROTECT, 
F5, 

NUMBER , 

F7) BIT (1 ) INIT (• 0' B) , 
2 RES BIT (1) INIT ('O'B) , 
2 NO FIXED BIN, 
2 AREA POINTER, 

2 STEP FIXED BIN(31,0) INIT(O), 
2 HEAD POINTER, 
2 NAME POINTER; 
DCL A CHAR(8) INIT(«B') ; 
DCL 1 LARAY, 
2 LOGHD (12) FIXED BIN, 
2 ARRAY (24) FIXED BIN(31,0); 
GTLOGSTR. STEP=- 1 ; 

GTLOGSTR. AREA= ADDR (L AR AY . LOG HD ( 1 ) ) ; 
GTLOGSTR. NAME= ADDR (A); 
CALL DPPPIF (GTLOGSTR. MACID) ; 



/* GETLOG DEFAULT STROCTURE ♦/ 

/* GETLOG MACRO ID */ 

/* RETURN CODE */ 

/* PARAMETER LIST FLAGS */ 

/* RESERVED */ 

/♦ A (LOGHEADER) IN HEAD */ 

/♦ RESERVED */ 

/♦ ON IF PROTECTION REQ'D ♦/ 

/* RESERVED */ 

/♦ NUMBERED ARRAY */ 

/* RESERVED */ 

/* RESERVED ♦/ 

/* ARRAY NUMBER */ 

/♦ DATA AREA ♦/ 

/* RELATIVE COPY NO */ 

/* A (LOGHEADER/TIME FIELD ♦/ 

/* A (ARRAY NAME) ♦/ 
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PL/I PUTLOG Interface 

This PL/I interface provi'ies the programmer the facilities of the PUTLOG 
service. The default structure, PTLOGSTE (defined below) , may be copied 
into the PL/I program via a ^INCLUDE PTLOGDEF;., 



DCL 


1 


PTLOGSTR, 




/* 


PUTLOG DEFAULT STRUCTURE */ 




2 


MACID FIXED BIN 


INIT (44) , 


/* 


PUTLOG MACRO ID */ 




2 


RC FIXED BIN 


INIT(O) , 


/* 


RETURN CODE */ 




2 


NAME POINTER, 




/* 


A (NAME/NUMBER/LIST) */ 




2 


HEAD POINTER, 




/* 


A (LOGHEADER/BLOCKLIST) */ 




2 


TYPE, 




/* 


PARAMETER LIST FLAGS V 






3 {F0,F1, 




/* 


RESERVED */ 






LOGHDR, 




/* 


A(LOGHEADER) IN HEAD */ 






BLOCK, 




/* 


A(BLOCKLISr) IN HEAD */ 






PROTECT, 




/* 


ON IF PROTECTION. P.EQ'D */ 






LIST, 




/* 


A (LIST FORM) IN NAME */ 






NUMBER) BIT(1) 


INIT (• 0' B) , 


/* 


A (NUMBER) IN NhME */ 






3 PUT BIT (1) INIT ( • 1 « B) , 


/* 


MUST BE ON V 


2 


PES BIT(1) INIT(« 


O'B) , 


/* 


RESERVED */ 


2 


BLKADD FIXED BIN 


INIT (0) ; 


/♦ 


DISPLACEMENT NEXT BLKNO */ 



PTLOGSTR 

Name of the default structure provided for the Special Real Time 
Operating System PUTLOG service requests. 

MACID 

A halfword binary value of 44 identifying the requested service to 
the interface routine. 

RC 

A halfword binary field containing a binary number return code from 
the PUTLOG service routine. See PUTLOG macro write-up for possible 
val ues. 

NAME 

The address of an array name, number or a list of array names or 
numbers. The flags LIST and NUMBER in the flag field TYPE define 
the contents of this field, 

LIST = 'O'B and NUMBER = '0»D 

Specifies the address of a name of a named array from which data is 
to be logged. 

LIST = «0'B and NUMBER = '1'B 

Specifies the number assigned to a numbered array from which data is 
to be logged in a halfword field binary field. 

LIST = M'B and NUMBER = 'O'B 

Specifies the address of a user-constructed list of array names from 
which data is to be logged. The name list will be a table of 8-byte 
entries with one valid array name in each entry. The first byte past 
the last valid entry will be set to X'FF' to indicate the end of the 
name list. 
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EXAMPLE: Name List 



ARRAYNAM 



HOUSTONfe 



TEXASfebb 



X'FF* 



LIST = '1'B and NUMBER = M'B 



Specifies the address of a user -constructed list of array numbers 
from which data is to be logged. The number list will be a table of 
halfword entries with one valid array number in each entry. The 
first byte past the last valid entry will be set to X»FF' to indicate 
the end of the number list. 



EXAMPLE: Number List 



0 



H'l' 


H'255' 


H'l 


39' 


X'FF 





HEAD 

The address of a logheader or blocklist or zero. The flags LOGHDR 
and BLOCK in the flag field TYPE define the contents of this field. 
If neither flag is set, HEAD is ignored, 

LOGHDR = '1«B and BLOCK = • 0« B 

Specifies the address of an array logging header- Information in 
this logging header will identify the copy of the array which is to 
be replaced in the log data set. 

The logging header is a 24-byte control block which precedes the 
array, both as the array exists in virtual storage and as is written 
to the logging array. The logging header which was retrieved as part 
of a previous GETLOG macro may be used to replace that copy in the 
log data set. 

BLOCK = M'B and LOGHDR = «0'B 

Specifies the address of a user-constructed list of block numbers 
and of core addresses. The data list will be a table of 6-byte 
entries. Each entry will contain a 1-byte flag field, a 3-byte area 
address, and a 2-byte block number. This will allow the user to 
update selected segments of the DA log array for block VS resident 
artays on demand basis. The latest log copy will be modified. 
However, the entire VS resident array is not logged; only the log 
block corresponding to the VS resident block specified will be 
updated. The actual log copy will not change; that is repeating 
PUTLOG macro calls with the BLOCK parameter will update the same log 
copy. A PUTLOG without the BLOCK parameter will cause the entire 
array to be logged to a new log copy. 
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EL^^I BLKLIST Entry Description 



FLAG 
BYTE 



AREA ADDRESS 



BLOCK 
NUMBER 



FLAG 
X« 40' 

X'80' 

AREA ADDRESS 
BLOCK NUMBER 



BYTE 

Indicates the last entry to be processed for a 
particular entry in the name list or number list. 

Indicates the last entry in the data list. 

Ignored. 

The number assigned to the data block to be retrieved 
and placed in the array described in the Name List 
or Number List . 



EXAMPLE: BLKLIST and Name List 



Name List 








Data List 




FIRSTbbb 






A(Area) 


HT 


SECONDbb 








A(Area) 


H'5' 


THIRDbbb 








X'40' 


A(Area) 


H'lO' 


X'FF 








X'40' 


A(Area) 


H'3' 










A(Area ' 


H'255' 










A(Arca) 


H'l' 










A( Area) 


H'2' 










A( Area) 


H'37' 










A(Area) 


H'l 86' 








X'80' 


A(Area) 


H"249' 



Blocks in first 
array 

Blocks in second array 



Blocks in third array 



TYPE — A 1-byte flags field specifying the parameter options. 

LOGHDR — See HEAD. 
BLOCK — See HEAD. 

PROTECT — If on, a lock is set to prevent any other modifications 
to the data base during the PUTLOG service. If off, 
the data will be logged without regard to other 
concurrent modifications. 

LIST — See NAME. 

NUMBER — See NAME, 

PUT — Must be on for PUTLOG service. 

BLKADD — The value to be added to HEAD to locate the next block 
number. A value must be specified. 

The PUTLOG service is invoked in PL/I by CALLing DPPPIF with a properly 
completed array name, array number, array name list, array number list, 
logheader address block list address and structure (PTLOGSTR or a 
similar structure). 
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The following example will POTLOG Array B. 



DCL 1 PTLOGSTR, 

2 MACID FIXED BIN INIT(4a), 
2 RC FIXED BIN INIT(O), 
2 NAME POINTER, 
2 HEAD POINTER, 
2 TYPE, 

3 {F0,F1, 

LOGHDR, 

BLOCK, 

PROTECT, 

LIST, 

NaMBER) BIT(1) INIT(«0«B), 
3 POT BIT(1) INIT(«1«B), 
2 RES BIT (1) INIT (• 0« B) , 
2 BLKADD FIXED BIN INIT (O) ; 
DCL A CHAR(8) INIT(«B»); 
PTLOGSTR. NAME = ADDR (A) ; 
CALL DPPPIF (PTLOGSTR, MACID) ; 



/* POTLOG DEFAULT STRUCTORE ♦/ 

/* PUTLOG MACRO ID */ 

/* RETURN CODE */ 

/* A(NAME/NOMBER/LIST) */ 

/* A (LOGHEADER/BLOCKLIST) */ 

/* PARAMETER LIST FLAGS */ 

/♦ RESERVED */ 

/* A(LOGHEADER) IN HEAD */ 

/* A(BLOCKLIST) IN HEAD */ 

/* ON IF PROTECTION REQ« D ♦/ 

/♦ A (LIST FORM) IN NAME */ 

/* A (NUMBER) IN NAME */ 

/* MUST BE ON V 

/* RESERVED */ 

/* DISPLACEMENT NEXT BLKNO */ 



Note that because HEAD was left zero, the array was logged at the 
current log copy plus 1. 



ELZI MIPLQG Interface 



This PL/I interface provides the programmer the facilities of the 
DOMPLOG service. The default structure DPLOGSTR (defined below), may 
be copied into the PL/I program via a ^INCLUDE DPLOGDEF;. 



1 


DPLOGSTR, 


/* 


DUMPLOG PARAMETER STRUCTURE */ 


2 


MACID FIXED BIN INIT(52), 


/* 


DUMPLOG MACRO ID */ 


2 


RC FIXED BIN INIT(O) , 


/* 


RETURN CODE */ 


2 


TYPE, 


/* 


SERVICE OPTIONS FLAGS */ 




3 (F0,F1,F2, 


/* 


RESERVED */ 




DISP, 


/* 


NEW - IF ON V 




F4, 


/* 


RESERVED */ 




LIST, 


/* 


LIST OF NAMES/NUMBERS */ 




NDMB, 


/* 


ARRAY NUMBER/NUMB. LIST */ 




F7) BIT(1) INIT(«0»B), 


/* 


RESERVED ♦/ 


2 


RES BIT(1), 


/* 


RESERVED */ 


2 


NO FIXED BIN INIT (0) , 


/* 


ARRAY NUMBER */ 


2 


START POINTER, 


/* 


A (START TIME) */ 


2 


STOP POINTER, 


/* 


(STOP TIME) V 


2 


AREA POINTER, 


/* 


A (USER DATA) */ 


2 


DDNAM CHAR(8) I NIT (• DOMPLOG •) » 


/* 


DEFAULT DDNAME */ 


2 


LIST POINTER; 


/* 


A (NAME/NUMBER LIST) */ 



DPLOGSTR 

Name of the default structure provided for the Special Real Time 
Operating System DUMPLOG service requests. 

MACID 

A half word binary value of 52 identifying the requested service to 
the interface routine. 

RC 

A half word binary field containing a binary number return code from 
the DOMPLOG service routine. See DUMPLOG macro write-up for possible 
values. 
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TYPE 

A flags field indicating the requested options to the DDMPLOG service 
routine. 

DISP 

Specifies whether the dumped copies are to be written at the beginning 

of the dump data set (DISP = M»B;) or added to the existing dumped 
copies (DISP = '0 »B ;) . 

If the disposition parameter specified on the DD card statement for 

this data set is either OLD or SHR and the data set is empty, then 

the first DUMPLOG request must specify NEW (DISP= • 1 » B ;) . 

Specifying DISP='1'B; on subsequent DUMPLOG requests will position 
a direct access data set to record one and will cause a tape data 
set to force the EOV before the log copies are written. 

LIST 

If on, specifies a list of array names or numbers is pointed to by 
the LIST pointer variable. 

NUMB 

If on, specifies numbered array (s) to be processed by this request. 
Either NO contains the array number, or LIST contains the address of 
a number list. 

NO 

Specifies the halfword number assigned to a numbered array for which 
the log array is to be dumped. LIST bit in TYPE must be off. 

START 

Specifies the address of a 6-byte time and day field beginning on a 
fullword boundary. The first four bytes will contain a time in 
1 0- mi 11 isecond units. The last two bytes will contain a binary value 
from 1 to 366 representing the day of the year. The logged copies 
of the array will be searched until a copy is found with a log time 
equal to or greater than the start time specified. If this parameter 
is omitted, dumping will commence with the oldest logged copy of the 
array. 

STOP 

Specifies the address of a 6-byte time and day field beginning on a 
fullword boundary. The first four bytes will contain a time in 
1 0- millisecond units. The last two bytes will contain a binary value 
from 1 to 3 66 representing the day of the year. The logged copies 
of the array will be dumped until the most recently logged copy has 
been dumped or until a copy is dumped with a log time equal to or 
greater than the stop time specified. If this parameter is omitted, 
dumping will terminate when the most recently logged copy of the 
array has been dumped. 

Note: The DUMPLOG routine will insert a byte of X»FF»into the first 

byte of the logging header of the last copy of each array dumped 
to the sequential data set. This function to indicate the end 
of the dump of each array to the user delog routine- 

AREA 

Specifies the address of a 256- byte area of user data to be contained 
in the dump header for each array on the sequential dump data set. 

DDNAM 

Specifies the name of a data definition statement which described a 
sequential data set to receive the dumped copies of the array from 
the log data set. If this parameter is omitted, the DD name *DUMPLOG« 
will be assumed as the default. 
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The output will consist of spanned variable length records. The 
blocksize of the data set defined by the DONAH parameter must be at 
least 264 bytes but no more than 32,760 bytes. The blocksize should 
be large enough to contain one array copy, the log header (24 bytes), 
the user dump header (256 bytes), if any, and the descriptor vords 
for variable length records (8 bytes) for maximum processing 
efficiency. 

LIST 

Specifies the address of the array name of the log array to be dumped 
(LIST bit of TYPE and NUMB bit are off) or the address of a list of 
array names or numbers (LIST bit of TYPE is on) . 

The name list will be a table of 8-byte entries with one valid array 
name in each entry. The first byte past the last valid entry will 
be set to X»FF» to indicate the end of the name list. 

EXAMPLE: Name List 



ARRAYNAM 

8 



H0UST0N6 
16 



TEXASfebb 
24 



X'FF 



The number list will be a table of halfword entries with one valid 
array number in each entry. The first byte past the last valid entry 
will be set to X*FF* to indicate the end of the number list. 



EXAMPLE: Number List 



0 

H'r 

2 
4 



H'255' 



H'139' 



The DUMPLOG service is invoked in PL/I by CALLing DPPPIF with a properly 
completed DPLOGSTR or a similar structure. 

The following example will DUMPLOG all the logged copies of array MS* 
beginning with the oldest copy. The dumped records will be at the 
start of the data set pointed to by DD name DUMPLOG. 
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DCL 1 DPLOGSTH, 

2 HACID PIXBD BIM INIT{52), 
2 RC FIXED BIN INIT(O) , 
2 TYPE, 

3 (P0,P1,P2, 
DISP, 

LIST, 
NHNB, 

P7) BIT(1) IHIT('0»B) , 
2 RES BIT (1) , 
2 NO PIXED Bin IHIT(O), 
2 START POINTER, 
2 STOP POINTER, 
2 AREA POINTER, 

2 DONAH CHAR(8) INI T ( • DOB PLOG • ) # 

2 LIST POINTER; 
DCL A CHAH(8) IMIT ('B* ) : 
DPLOGSTR.TYPE. DISP = M'B; 
DPLOGSTR.LIST = ADDR(A); 
CALL DPPPIP(OPLOGSTH. HACID) ; 



PL/I Optiwizinq Compiler Pac^lities 

The method of supplying PL/I Optimizing compiler executior time options is 
not conpatible ¥ith the Special Real Time Operating Systea. Therefore, a 
program, DPPPLIO, is provided to allow the user to exercise some of these 
options. The execution ti»e options which DPPPLIO passes to the prolog 
are, NOBBPORT, SPIE, NOSTAB, NOCOIJNT, NOFLO« and ISASIZE. The ISASI2E 
■ay be supplied by the PL/I proaraa by declaring an external fullword, 
ISASIZE, and assigning as initial data the required TSA size in bytes, 
see example. 

DCL TSASIZE EXTERNAL PIXED BIN(17) INIT(U096); 

If the external is not provided or is zero, then a default of 2048 bytes 
is assumed. All values supplied irill automatically be rounded upward to 
a Bultiple of eiaht. 

To determine the optimum ISA size to request, the report option aay be 
used. To do this the user must modify the load module at the location 
DPPPLIEO. DPPPLIEO is a full word external syabol which will appear in 
the linkage* editor map of the load module. Set bits 0 and 1 of byte 0 at 
DPPPLIEO to 1 and 0 respectively. Execute the prooraa in such a aanner 
as to force execution of the epilog which will generate the necessary 
report. fft*^r sufficient test time modify the PL/I program to supply 
the snallest required fixed ISA size and relink edit the PL/I proqraa. 



/* DDHPLOG PARABETEB STBOCTORE 

/* DUHPLOG MACRO ID ♦/ 

/* RETOHN CODE */ 

/♦ SERVICE OPTIONS PLAGS ♦/ 

/♦ EBSBRVED ♦/ 

/♦ NE« - IP ON ♦/ 

/* RESERVED */ 

/♦ LIST OP NAflE/NOHBERS */ 

/♦ ARRAY NOaBEB/HOHB.LIST ♦/ 

/* RESERVED */ 

/♦ RESERVED ♦/ 

/* ARRAY NUHBER */ 

/• A (START TIHE) ♦/ 

/♦ A (STOP TTHE) */ 

/♦ A(OSER DATA) */ 

/♦ DEFAULT DDNAHE ♦/ 

/♦ A (MAHE/NUMBBR LIST) */ 
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special Real Time O perating S yste a FORTRA N Interfaces 

This portion of the aanual explains the prograaaing considerations for 
FORTRAN programs to be run under Special Real Tiae Operating System 
environment. FORTRAN programs which do not use Special Real Tiae 
Operating Systea services should follon standard procedures as described 
in the FORTRAN Prograaaer 's Guide . Fora No. GC28-6817. 

The reaainder of this section explains procedures pertinent only if 
Special Real Time Operating Systea services will be used in FORTRAN 
prograas. The user should be aware that these services are intended 
for FORTRAN prograas which are invoked via the PATCH function. Other 
means of executing FORTRAN (such as LINK, CALL, XCTL) using these 
services should be used only by prograaaers who are aware of the 
interfaces between FORTRAN and the Special Real Tiae Operating Systea. 

The interface routines described here use FORTRAN COMHON areas to pass 
and receive paraaeters. It should be noted that, when using the G 
level FORTRAN coapiler, the variable naae that is passed to the 
interface routine (s) aust be the naae of a variable within the COHHON 
area and not the naae of the COHHON area. 



Enhanceaents to F ORTRAN Data Hani pulation and Hoveaen t 

This section describes three enhanceaents provided to the FORTBAN 
prograaaer to interface with Special Real Tiae Operating Systea: 

1. Identification of the computer storage address of one variable 
and setting another variable to that value. 

2. Execution of storage bits. 

3. Movement of up to 32,767 computer storage bytes of data from 
one location to another. 

The FORTRAN programmer will discover that one or more of these 
capabilities is probably needed when using the capabilities described 
in the remainder of this section. 



lADDR Function 

This function computes and returns to the caller the 32- bit address 
requested and stores it at the desired location. 

X=IADDR (Y) 



ORBIT Subroutine 

This subroutine ORs the specified bit aask into the specified address. 
The location to be aodified aust be specified first in the CALL 
paraaeters. 

L0GICAL*1 FF/ZFF/ 



CALL ORBIT (X,FF) 
NDBIT Subroutine 

This subroutine ANDs the specified aask with data at the specified 
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address. The location to be aodified must be specified first in the 
call parameters. 

L0GICAL*1 SF/Z7F/ 



CALL NDBIT(X,SF) 
COPY Subroutine 

This function moves up to 32,767 contiguous bytes of data from one 
location to another. More than one move operation can be specified 
in the same call. The format of the CALL subroutine is as follows: 

CALL COPY (INLIST^OUT^ ,0^1^,., ,OUT J 

whero INLIST specifies an address variable or a common area consisting 
of address variables. (An address variable is one which has been set 
using the lADDR function to contain the address of, or point to, a 
data area.) The address variable (s) in IM,IST should point- to the data 
area from which data is to be moved- The variable OUT ^ , . * . , OOT^ should 
be the labels for the data area to vhich the data is to be moved. The 
number of copy operations will be equal to the number of OOT^ 
variables. Data will be moved to the OOT^ data area from the data 
area addressed by the first address variable of INLIST, data will be 
moved to the OUT^ data area from the data area addressed by the second 
address variable of INLIST, and so on until ODT„ has been likewise 
processed. 

If either ODT. or the corresponding address variable of inlist is zero 
no move takes place for that 013 1 . . The copy operation proceeds to the 
next OUT.^, . 

The length of each move will be determined independently for each GOT. 
either by the first halfword of the OUT. data area, or by the first 
half word of the data area pointed to by' the corresponding address 
variable of INLIST. The length of the move will be equal to the 
smaller positive value of the two halfwords, as zero and negative 
values are not recognized. (No move will take place for this OUT, if 
neither halfword referred to is positive.) Note that the first halfword 
of both areas is included in the move, and the two bytes occupied by 
the length must be included in the length specification. 

For example, moving one data area, INA1, to another data area, 0UTA1, 
is accomplished as follows: 

G iven : 

COHMON/INAI/INHALF, INF (30) 
INTEGER INHALF*2, INF*2 
C0MK0N/0UTA1 /OUTHAF, OUTF (7 0) 
INTEGER 0UTHAF*2, 0UTF*2 

Then code: 

lNHALF = 30*2-«-2 Set the first halfword of the input area 

equal to its length. 

0UTHAF=7 0*2+2 Set the first halfword of the output area 

equal to its maximum length - in case the 
input area's length varies. 
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INADD=IADDR(INHALF) Set the address variable INADD to point to 

labeled common area INA1. 

CALL COPY (INADD, OUTHAF) 

This causes the common area INA1 to be moved in its entirety (62 bytes) 
to the common area O0TA1. Note that the value of OOTHAF would be 62 
after the MOVE operation. 

The next example describes moving several common areas (C0M1, C0H2, 
COM3) to output common areas (OOTI, 0UT2, C0aT3) . It is assumed that 
the first half word of each common area has been set to its desired 
length. 

Given: 

COMMON/COM VCHALF1 . . . 
C0MM0N/C0M2/CHALF2.- . 
C0KM0N/C0M3/CHALF3.. . 
C0HM0N/INC0M/IN1 ,IN2,IN3 
INTEGER IN1,IN2,IN3 
COMMON /0UT1/0HALF1. ., 
COMMON /0UT2/0HALF2. 
COMMON /OOT3/OHALF3. -. 

Then code: 

INI =IADDR (CHALF1) Set the address variables 

IN2=IADDR (CHALF2) to point to their common 

IN3=IADDR (CHALF3) areas. 
CALL COPY (IN1 ,OHALF1,OHALF2,OHALF3) 



Lscatinfl InEUl Pa ^r^ me ter (s) Af^er Being P ATCHed 



This section explains the coding 
data which may have been specifie 
the section on the PATCH macro fo 
parameters. The only requirement 
the PA^iCH macro can specify a lis 
the user in his PROBL. This disc 
re-entered at the beginning for e 
processed. A FORTRAN program may 
several times when actually being 
This is described in the section 
FORTRAN Program". 



of FORTRAN program to interrogate the 
d via the PATCH function. Refer to 
r a detailed discussion of the PATCH 

of this discussion is to know that 
t of input parameters to be passed to 
ussion applies to a program which is 
ach execution of the function to be 
be coded to be logically entered 
entered at the beginning only once, 
entitled, "Repeated Execution of a 



The FORTRAN program receiving control due to the PATCH can gain access 
to this PROBL parameter list by including a call to a special interface 
routine (DPPFPM) and having a predefined common area properly 
initialized, as described. The common area is described in the 
following example and will be called PARH throughout this write-up. 

FARM 

0 +2 



+4 
+8 

+12 



PRMAC 



PRMRC 



PRXCVT 



PRMRES 



PRMADD 



While the first two halfwords, PRMAC and PRMRC, must be initialized to 
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zero prior to calling DPPFPM, the remainder of the common area need 
not be initialized. 

Following is a layout of the common area PARK in FORTRAN code, with an 
explanation of each variable as they pertain to this section. 



c 

C COMMON NAMED'PARM'- 
COMMON/PARH. PRHAC 

INTEGER*2 PRMAC 
COflMON/PARM/ PRMRC 

INTEGER*2 PRMRC 
COHMON/PARM/PRXCVT 

INTEGER*^ PRXCVT 
COMMON/PARM/PRMRES 

INTEGER*^ PRMRES 
COMMON/PARM/PRMADD 
INTEGER*^ PRMADD 
C END OF COMMON NAMED 
C 

PRMAC 

A halfword Vai-iable reserved for use by DPPFPM. It must be initialized 
to zero prior to calling DPPFPM (the first call only) and its contents 
will have no meaning to the FORTRAN programmer. It should not be 
altered after the first call to DPPFPM. 

PRMRC 

A halfword variable which will contain the return code as set by 
DPPFPM. This variable should be set to zero prior to calling DPPFPM. 
Its subsequent contents have no meaning to the FORTRAN programmer when 
calling DPPFPM solely to gain access to the PATCHed input parameters. 
(The section entitled, "Repeated Execution of FORTRAN Program" 
describes another use of the program DPPFPM and common area PARM in 
which this variable is pertinent). 

PRXCVT 

This fullword variable^ which need not be initialized, contains the 
address of the XCVT after calling DPPFPM. This variable does not 
pertain to the present discussion. 

PRMRES 

This fullword variable, which need not be initialized, contains the 
address of the Resource Table for this task after calling DPPFPM- 
This variable is not pertinent to the present discussion on input 
parameters. 

PRMADD 

This fullword variable, which need not be initialized contains the 
address of the Problem Parameter List (PROBL) for the causative PATCH. 
It is through this variable that the FORTRAN programmer gains access 
to his PROBL, which contains the input parameters or pointers to the 
input parameters. 

The PROBL, pointed to by the variable PRMADD (within common PARM), 
should also be described by a labeled common area, which shall 
henceforth be called PROBL. The PROBL has one of two formats, 
depending on whether this program is PATCHed via a PATCH macro (from 
an already executing program) or via an input control stream PATCH 
CAFD. In either case, the length of the table varies with the number 
of parameters passed on the PATCH, so the common area (PROBL) should 
be specified according to the maximum number of parameters expected. 
The following example depicts the two formats of the PROBL, 



-PARAMETER TABLE FOR RECEPTION OF PATCH 



» PARM' 
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PROBL from 
PATCH Macro 



+ 2 +3 




PROBL from 

an Input Control Stream PATCH Card 



Length of PROBL 


00 


ID 


(Reserved Flags) 


Length 
of first 
parameter 


Address of 
first parameter 



(One fullword per parameter) 



Length 
of last 
parameter 



Address of 
last parameter 



Note that the first word of both formats is the same and that while 
the format of the remainder is fixed in the PATCH card type, the foraat 
of the remainder is flexible in the PATCH macro type. In most cases 
the PROBL of a PATCH macro, when used in conjunction with FORTRAN 
programs, will be set up to consist of data rather than pointers to 
data as in the PATCH card type. 

The common area, then, for the PROBL would be coded as follows: 



COMMON/PROBL/PRBLNG 
TNTEGEE*2 PROBLNG 

COMMON/PROBL/ID 
INTEGER*2 ID 

COnnON/PROBL/PROBPI 
INTEGER*4 PR0BP1 



PPBLNG 

The total length in bytes of this PROBL, including this halfword. 

ID 

The ID value specified on the PATCH CARD or macro (defaults to zero) . 

PR0BP1 

A fullword variable which (1) contains the first PATCH parameter or 
(2) contains the address of the first PATCH parameter. (1) or (2) is 
thf user's (caller's) option- 

The Special Real Time Operating System initialization process allows 
d PATCH to be executed under control of a PATCH card. The format of 
the parameters that may be specified with the PATCH card are such that 
passing parameters from the PATCH card may not be practical, without 
an assembler language routine specially written for this purpose- 
In the following example, assume that the FORTRAN program will be 
PATCHed by a program (already in execution) with which a common format 
for the pisOBL has been previously established, suppose that the 
following statements describe this PROBL format and appear in the 
FORTRAN program. 
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COMMON/PROBL/PRBLNG, ID,PROBP (1 0) 
INTEGER PRBLNG»2, ID*2,PROBP*4 

These cards indicate that 10 fallword parameters will be passed to this 
FORTRAN program. 

Ther, to interrogate the parameters within the FORTRAN program, code 
the following: 

COMWON/PARM/PRMAC,PRMRC,PRXCT,PRMRES,PRMADD 
INTEGER PRM AC*2,PRMRC*2,PRXCVT, PRMR ES ,PRM ADD 

These cards defined the common area PARM previously explained. 

PRMAC=0 These statements initiali2e the 

PRMC=0 common area PARM as required. 

CALL DPPFPM (PRMAC) Cause the common area PARM to be properly 

filled in. 

PRBLNG=44 Set length of PROBL to maximum expected. 

CALL COPY (PRMADD , PRBLNG) Cause the common area PROBL to be filled in 

as per the PROBL of the PATCHING program. 

The variables PROBP(I) through PROBP(IO) will have the values specified 
in the PATCH and can be referenced normally. 



R epeate d Executions of a FORTRAN Progra m 

Thi'^ section describes the procedure to be used for a FORTRAN program 
which is to be repeatedly executed in a realtime environment* 

Under standard executing conditions when a FORTRAN program is executed 
a second time after completing one execution, a fresh copy is fetched 
and both prologue and epilogue are executed again. This fetching of 
a fresh copy and the re-executing of the prologue/epilogue can sometimes 
be avoided when executing a FORTRAN program under the Special Real Time 
Operating System. This is done by coding multiple calls to an interface 
program (DPPFPM) in a certain sequence and by having a predefined common 
area properly initialized. 

The description of the common area, hereafter called PARM, was presented 
in the section entitled "Locating Input Parameters after being PATCHed" 
and will be repeated here with explanations pertinent to this section. 
The following example depicts the PARM common area. 



PARM 

+2 



PRMAC 

+4 

PRXCVT 

+8 



PRMRC 



PRMRES 

+ 12 

PRMADD 
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The FORTH AN-coded statements for the specification of the FARM comnon 
area follows: 

C 

C COMMON NAMED' PARM»--PARAMETER TABLE FOR RECEPTION OF PATCH 
COHMON/PARM/PRMAC 

INTEGER*2 PRWAC 
COMMON/PARM/PRMRC 

INTEGER*2 PRMRC 
COMMON/PARM/PRXCVT 

INTEGER*a PRXCVT 
COMMON/PAR M/PRMRES 

INTEGER*^ PRMRES 
COMMON/PARM/PRMADD 
INTEGER*a PRMADD 
C END OF COMMON NAMED 'FARM* 
C 



PRMAC 

This halfword variable should be initialized to zero prior to the 
first call to DPPFPM only. It will be used by DPPFPM and should not 
be subsequently altered by this FORTRAN program. Its contents will 
be of no significance to the FORTRAN programmer. 

PRMRC 

This halfword variable should be initialized to zero prior to the 
first call to DPPFPM only. It is used as both an input variable and 
an output variable by the FORTRAN program following An in-depth 
explanation of the use of this vital parameter follows the remaining 
description of the PARM common area. 

PRXCVT 

This fullword variable, which need not 
address of the XCVT. This variable is 
di scussion . 

PRMRES 

This fullword variable, which need not 
address of this task's resource table, 
to our present discussion. 

PRMADD 

This fullword variable, which need not be initialized, contains the 
address of the PROBL (problem parameter list) for this PATCH. Refer 
to the section entitled "Locating Input Parameters after being PATCHed" 
for a full explanation of accessing the problem parameter list. 

To understand the use of the PARM common area (in particular the 
variable PRMRC) in conjunction with multiple calls to DPPFPM, the 
concept of a work queue for a task must be understood. The FORTRAN 
program should be capable of performing a specified function when 
invoked, and if this function is requested again (or several times) 
under the same task, then the second request will be the first entry 
in the work queue of that task. 

When the original request is serviced and the FORTRAN program has 
returned, the second request (first entry in the work queue) will be 
honored and the FORTRAN program will be executed again. When the 
FORTRAN program has returned and no additional requests are waiting, 
a condition indicated by an empty work queue, the Special Real Time 
Operating System will place this task in wait state until such a request 
is made. If a request is made for a different program to be executed 
unc^er this task, the Special Real Time Operating System will allow this 
FOKTRAN program to be purged- 



be initialized, contains the 
immaterial to our present 



be initialized, contains the 
This variable is immaterial 
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If the author of the FORTRAN program foresees no entry in the work 
queue for this program's task at the completion of the program or at 
a later time, he should return as in standard FORTFftN (i.e., he need 
not call DPPFPM at all except for input parameter considerations) - 

Given that entries in this task's work queue for this program are 
expected on completion of the processing of this PATCH, the programmer 
can avoid the overhead of program fetch and epilogue/prologue by not 
returning normally but instead, calling DPPFPM again. (The first call 
to DPPFPM must have been done). Through the use of the variable PRMAC 
(maintained by DPPFPM), DPPFPM will know that this is not the first 
call and consider it a RETURN. DPPFPM will then locate the first entry 
in the work queue for this task (or wait until there is one) and, if 
the entry is for this FORTRAN program, properly fill in the PARM common 
area according to the PATCH causing this work queue entry. 

If the previous PATCH (the one for which processing has just completed) 
had specified an ECB for posting, then that ECB will be posted with a 
completion code equal to the value in the variable PRMRC, which can be 
set by this program. If the first entry in the work queue was for 
another program, then this FORTRAN program should return normally, 
yielding this task to the new request- This This condition will be 
indicated by a non-zero value in PRMRC. This setting of PRMRC by DPPFPM 
is done on each call, including the first call, so the FORTRAN coder 
can surmise that only one call to DPPFPM is needed, followed by a RETURN 
if PRMRC is not zero. At the end of processing, or anywhere a normal 
RETURN would be coded, he would GO TO the statement of the CALL to 
DPPFPM. 



The following example illustrates the use of the multiple calls to 
DPPFPM for a FORTRAN program written with the expectation that it would 
be PATCHed repeatedly under the same task. 



Given: 



A FORTRAN program that expects to be PATCHed (via PATCH macro) with 
different PATCH IDs to indicate various macro processing options 
desired. 



Then code: 



COMMON/PARM/PRM AC , PRMRC, PRXCVT, PRMRES ,PRMADD 
INTEGER PRM AC*2,PRMRC*2, PRXCVT, PRMRES, PRM ADD 
COM MON/PROBL/PR BL NG , ID, PR0BP1 
INTEGER PRBLNG*2, ID*2,PR0BP1 

These cards define the required coamon areas, 

PRMAC=0 Initialize the PARM common 

PRMC=0 area as required 



1000 CALL DPPFPM (PRMAC) Call DPPFPM to get PATCH ID parameters 

IF (PRMRC. NE. 0) RETURN Non-zero indicates a different program 

has been PATCHed to execute under this 
task. Return and give up control of 
this task- This c ondition w il l not 
occur on the first cal l. 

A zero value indicates that variables in the PARM common area 
(especially PRMADD) have been set according to the PATCH- Proceed with 
processing. 
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PRBLNG=12 Set PRBLNG for a copy operation. 

CALL COPY (PRMADD, PRBLNG) Copy the PROBL for this PATCH to the comaon 

area PFOBL, 

Nov inspect ID and proceed processing. 

When processing is completed, set PRMRC according to a previously agreed 
upon return code (agreed upon with the author of the program vhich 
executed the PATCH this program has been processing). 

PRMRD= return code 

GO TO 1000 This causes another call to DPPFPli indicating that 

processing is completed for this PATCH and the 
program expects another. 

Note: The input parameters of each PATCH could also be interrogated 

in this example. Refer to the previous section for a description 
of this procedure. 



Seecial Real Time Ope rating S yste m Online Macro S ubroutin es for F ORTR AN 

This section explains the coding of each of the online macros provided 
to the FORTRAN programmer by the Special Real Time Operating System. 
Each of these functions is provided to assembler language programmers 
through macro calls. There is a parallel (but more detailed) write-up 
on each function in the online macro section of this manual. Although 
this section may attempt to explain to varying degrees the functions 
themselves^ the main purpose here is to describe the format of the 
COMMON areas required for invoking each function and point out 
peculiarities where pertinent. 



FOETRANzEMCH Interface 

The PATCH service provides the programmer the facility of creating work 
queues for passing parameters to programs executing under the special 
Real Time Operating System. The following FORTRAN statements define 
the parameter list for this service: 
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c 

C COMMON NAMED 'PATCH' — PARAMETERS NECESSARY FOR PATCH FROM 
C FORTRAN 

C 

COMMON/PATCH/P ATMAC 

INTEGER*2 PATMAC 
CO H MON/P AT CH/P AT RC 

INTEGER*2 PATRC 
COHMON/PATCH/PATPRM 

INTEGER*^ PATPRM 
COWMON/PATCH/PATASK 

INTEGEP*4 PATASK(8) 
CO HMON/P ATCH/P AT EP 

LOGICAL+1 PATEP(8) 
COMMON/PATCH/PAT NAM 

L0GICAL*1 PATNAM(8) 
CO M MO N/P AT CH /P AT Q 

INTEGER*2 PATQ 
COMMON/PATCH/P ATV 

INTEGER*2 PATV 
CO M MO N/P AT CH/P AT EC B 

INTEGER*** PATECB 
COMMON/PATCH/P AT RES 

INTEGER*4 PATRES(2) 
COMMON/PATCH/P ATCBX 

INTEGER*^ PATCBX 
COMMON/PATCH/P AT FLG 

L0GICAL*1 PATFLG 
C END OF COMMON NAMED 'PATCH* 
C 



PATMAC 

A halfword binary constant value of zero to identify a PATCH service 
request to the interface routine. 

PATRC 

A halfword binary field containing the return code from the service 
routine. See PATCH macro write-up for possible values. 

PATPRM 

A fullword address of the parameter list being passed. The format is 
a halfword binary value (minimum value is U) describing the length of 
the entire parameter list, (including length and patch ID) followed 
by a halfword binary value from 0 to 255 called the PATCH ID with the 
remainder of the list being the parameters. The diagram below 
represents the format of a PATCH problem parameter list. 



PATCH ID 



LENGTH 



PARAMETERS 



PATASK 

An 8-byte character field containing the name of the task being 
PATCHed. If the task does not exist, one by that name will be created. 
If PATASK is all blanks, the PATCHed program will execute under a 
dependent task. 

PATEP 

An 8-byte character field containing a valid entry point name which 
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is the name of the program to be scheduled under the task being created 
with the PATCH. 

PATNAM and PATV 

Specifies an 8-byte character field containing the task name for 
determining priority and a halfword binary value which will determine 
that priority relative to the task name in PATNAM, 

PATQ 

A halfword binary value from 0 to 235 specifying the number of work 
queue entries to be allowed for the new independent task. If 0 is 
specified, the task accepts one PATCH, works on that request, and, 
when completed, waits for the next request- If a PATCH is requested 
for that task while it is busy, the request is not executed. If the 
queue length is 1, the task can accept one PATCH even while it is 
busy. Any PATCH parameters waiting in the queue when a task completes 
processing of the current request will be executed one at a time, with 
the start of the queue being executed first. This procedure is the 
same for all queue values from 0 to 255. 

PATECB 

The address of a fullword event control block (ECB) within a PATCH-WAIT 
parameter list of the common area WAIT, The ECB is posted when 
processing for this PATCH completes, 

PATPES 

Filler position for required space for PATCH MACRO (not usable by 
programmers) . 

PATCBX 

A fullword address of the TCB extension control block (TCBX) for an 
existing independent task. The TCBX address is stored by the interface 
routine after each PATCH service call- Use of this parameter with 
all successive PATCHes to the same independent task after the initial 
PATCH will reduce system processing time. Note that the other 
parameters must still be specified for verification or in the event 
the task has been DPATCHed. 

PATFLG 

The PATCH option flags as described below: 

X»40» — This PATCH is intended for the MASTER partition, 

Xi20» — This PATCH is intended for the SLAVE partition. 

X«08« — If this work request is pushed off the queue, the ECB is to 
be posted with a REPATCH control block address. 

Xi04» — Place the work request at the start of the work queue. If 
off, the request is queued last, 

X'02' — Place this work request on the task DPATCH queue to be 
executed when a DPATCH is issued for this task, 

X'01' — Specifies a DELETE is to be issued for the load module named 
previously after processing completes for this PATCH, 

X«00« — Execute this PATCH last. 

All combinations are valid except X*04* and X'02* must not both be 
set to 1. 

The PATCH service may be invoked by assigning values to the above 
defined variables and CALLlng DPPFIF passing the common area as the 
(only) parameter. Exaaples of using the PATCH facility follow. 
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E\amples 1 and 2 use the following parameter lists, variables, and 
constants as expressed in FORTRAN statements: 

BLOCK DATA 

COHMON/PATCH/PATMAC,PATRC,PATPRM,PATASK (2) , PATEP (2) ,PATNAM(2) , 
1PATQ,PATV,PATECB, PATRES (2) , PATC BX , P ATFLG 

INTEGER PATMAC*2/0/rPATRC*2/0/,PATPRM,PATQ*2/V,PATV*2/0/r 
1PATECB, PATRES,PATCBX 

LOGICAL PATASK*4/' » ,PATEP*4 , PATNAM*a/« /, ' », 

1PATFLG*1 

COMMON/WAIT/WTM ACWTRC, WTECB 

INTEGER WTMAC*2/60/, WTRC*2/0/,WTECB/0/ 

END 

(The above common areas should be repeated in the main program 
without data initialization. The following statements are in 
MAIN only.) 

LOGICAL *4 TN(2) /'OPPZ* , 'TSOOV/TP (2)/«DPPZ» , 'TS 13 V 
L0GICAL*4 DP(2) /' DEPE' , 'NDX V^BLK (2) /• «/ 

Example 1 

In this example, the task DPPZTSOO is to be created with a queue length 
of 1. Program DPPSTS13 is to be executed, and the parameter list is 
to contain only the length field and a PATCH ID of 10. The new task 
is to have the same priority as the task issuing the PATCH, Note that 
if the task already exists, the P ATFLG (all bits off) indicates this 
work request will be queued behind any others on the queue. 

PRBLNG=4 
ID = 10 

PATPRf1=IADDR (PRBLNG) 
DO 100 1=1,2 
PATASK (I) =TN (I) 
100 PATEP(I) =TP(I) 

CALL DPPPIF (PATMAC) 

Example 2 

In this example, assume that the CALL in Example 1 has returned, and 
a dependent task is to be created at a priority of 10 less than the 
task DPPZTSOO and that program DEPENDX is to be passed a parameter list 
PLTCH ID of 2. The PATCHing program will WAIT for the dependent task 
to complete. The WAIT function is executed via a CALL to the interface 
routine using the WAITSTR structure. 

CALL DPPPIF(PATM AC) 
ID = 2 

DO 200 1=1,2 
PATASK(I) =BLK (I) 
PATEP (I)=DP (I) 
200 PATNAM(I) =TN(I) 
PATV=10 

PATECB=IADDR (WTECB) 
CALL DPPPIF (PATMAC) 
IF(PATRC.GE.8) GO TO 400 
CALL DPPPIF (WTM AC) 
400 CONTINUE 
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FORTRAN PATCH -WAIT Interface 

This interface provides the FORTRAN programmer with the facility to 
wait for the completion of a WQE generated by a PATCH- The following 
FORTRAN statements define the interface parameter list: 

c 

C COMMON NAMED 'WAIT* — PARAMETER TABLE FOR WAIT 

COMMON/WAIT/WTHAC 

INTEGER*2 WTMAC 

COMMON/WAIT/WTRC 

INTEGER*2 WTRC 

COMMON/WAIT/WTECB 

INTEGER*^ WTECB 
C END OF COMMON NAMED 'WAIT' 
C 

WTMAC 

A halfword binary constant value of 60 identifying the requested 
service to the interface routine- 

WTRC 

A halfword binary number containing the high order byte of the 
completion code from the PATCHed program. See PATCH macro for possible 
values. It should be initialized to zero. 

WTECB 

A fullword binary field containing the 3 low order bytes of the 
completion code from the WQE just processed or the address of a REPATCH 
control block- The value of this field is governed by the contents 
of WTRC- It should be initialized to zero. 

Note: For this interface, WTRC will never be zero when the interface 
returns to the FORTRAN program. 

Example 2 of the FORTRAN-PATCH interface shows the correct method for 
using this service. 



FORTRAN-DPATCH Interface 

The DPATCH facility provides the programmer the method of destroying 
tasks which were created by the PATCH service. The following FORTRAN 
statements define the parameter list for this service: 

C 

C COMMON NAMED 'DPATCH* 

COMMON/DPATCH/DPRES 

INTEGER*2 DPRES 

COMMON/DP ATCH/DPMAC 

INTEGER*2 DPMAC 

COMMON/DP ATCH/DPRC 

INTEGER*2 DPRC 

COMMON/DP ATCH/DPTYP 

TNTEGER*2 DPTYP 

COMMON/DP ATCH/DPTSK 

L0GICAL*1 DPTSK(8) 
C END OF COMMON NAMED 'DPATCH* 
C 

DPPES 

A halfword field inserted to align DEPTSK on a fullword boundary. 

DPMAC 

A halfword binary constant value of 8 identifying to the interface 
routine the required service. 
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DPP.C 

A half word binary field containing a binary number return code from 
the service routine. See DPATCH macro write-up for return codes. It 
should be initialized to zero. 

DPTYP 

A halfword binary value specifying the DPATCH service requested. If 
0 is specified, the task is deleted immediately or when the currently 
executing work request completes. Any work queued to the task is 
posted as deleted. If U is specified, the task is deleted only if 
its work queue is empty. This does not prevent new work from being 
queued. If 12 is specified, the task is deleted even if it is active. 
See the DEPATCH function under ONLINE MACRO for further explanation 
of the DEPTYP operand in the DEPATCH function- 

DPTSK 

Two logical fullwords specifying the name of the task being deleted. 
If blank, the current task is deleted. If the task is active, the 
program that is running will be ABENDed. 

The following example will force the task named •BOLDTASK* to be 
DPATC Hed immediately regardless of its active state and the amount of 
queued work. If the task is active, the running program will be 
ABENDed. 

C rOPTPAN DEPATCH EXAMPLE 
BLOCK DATA 

COMMON/DEPrCH/DEPRES,DEPM AC, DEPRC, DEPTYP, DEPTSK (2) 
INTEGER DEPMAC*2/8/,DEPRC*2/0/, DEPTYP*2/0/, DEPRES*2 
LOGICAL DEPTSK*U 

END 

(The above common areas should be repeated in the main program 
without data initialization. The following statements are in 
MAIN only.) 

LOGICAL A*a (2) /'BOLD' , ' TASK •/ 



DEPTSK(1) =A (1) 
DEPTSK (2) =A (2) 
DEPTYP=12 

CALL DPPPIF (DEPMAC) 
FORT RAN -REP AT CH Interface 

This FORTRAN interface provides the programmer the facilities of the 
Special Real Time Operating System REPATCH service. The following 
FORTRAN statements define the parameter list for this service: 
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c 

C COMMON NAMED 'RPATCH* — PARAMETER TABLE FOR RPATCH 
COWWON/RPATCH/RPMAC 

INTEGER*2 RPMAC 
COMMON/RPATCH/RPRC 

INTEGER*2 RPRC 
COMMGN/RPATCH/RPTYP 

INTEGER*^ RPTYP 
COMMON/RPATCH/RPCB 

INTEGER*!* RPCB 
COMMON/RPATCH/RPTSK 

LOGICAL*! RPTSK(8) 
COWMON/RPATCH/RPEP 

L0GICAL*1 RPEP(8) 
COMMON/RPATCH/RPRTK 

LOGICAL*! RPRTK(8) 
COMMON/RPATCH/RPQOE 

TNTEGER*2 RPQUE 
COMMON/RPATCH/RPVAL 

INTEGER*2 RPVAL 
COMMON/RPATCH/RPECB 

INTEGER*^ RPECB 
COMMON/RPATCH/RPRES 

INTEGER*^ RPRES(2) 
COMMON/RPATCH/RPTCB 

INTEGER*^ RPTCB 
COMMON/RPATCH/RPFLG 

LOGICAL*! RPFLG 
COMMON/RPATCH/PPAD 

LOGICAL*! RPAD(3) 
COHMON/RPATCH/RPPRM 

INTEGER*^ RPPRM (3) 
C END OF COMMON NAMED 'RPATCH' 
C 

RPMAC 

A halftford binary value of 12 identifying to the interface routine 
the required service. 

RPRC 

A halfword field containing a binary namber return code from the 

REPATCH/PATCH service routine. See EEPATCH macro write-up for BEPATCH 
and related PATCH return codes. 

RPTYP 

A fullwoud binary value indicating the interface routine service 
required : 



0 — The REPATCH control block is to be copied to this parameter list 
for alteration prior to REPATCH. 

4 — Issue REPATCH TYPE = EXEC. 

8 — Issue REPATCH TYPE = PURGE. 

RPC3 

A fullword binary field to contain the REPATCH control block address 
placed in the WTECB when WTRC equals 68. The value in WTECB must be 
moved to RPCB before any interface call except the first interface 
call RPTYP = a or a following a RPTYP = 0 interface call. 

RPTSK 

Two U-byte logical words containing the name of the task being 
referenced by this PATCH. 
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RPEP 

Two 4-byte logical words containing the name of the program to be 
scheduled under task specified in RPTSK. 

RPRTK and RPV AL 

Specifies two 4-byte logical words containing a task name and a 
half word value which will determine the priority of the new task 
relative to the named task in RPRTK« 

RPQUE 

A halfword specifying the number of work queue entries to be provided 
for a new independent task. 

RPECB 

Specifies the address of the ECB within a COMMON/WAIT area which is 
to be used in a CALL DPPPIF. This ECB is posted when processing for 
this PATCH completes. The ECB which contained the REPATCH control 
address may be reused and will be if this parameter is left unchanged. 

RPRES 

Filler position required by REPATCH macro (not used by programmer). 

RPTCB 

Contains the address of the TCB extension control block for an existing 
independent task. 

RPFLG 

The PATCH option flags as described below: 

X»40' — This PATCH is intended for the MASTER partition. 

X«20« — This PATCH is intended for the SLAVE partition. 

X*08* — If this work request is pushed off the queue, the ECB is to 
be posted with a REPATCH control block address. 

X»OU' — Place the work request on the front of the work queue. If 
off, the request is queued last. 

X»02' — Place this work request on the task DPATCH queue to be 
executed when a DPATCH is issued for this task. 

X'01« — Specifies that a DELETE is to be issued for the load module 
named above after processing completes for this PATCH. 

Codes X'04' and X*02' are mutually exclusive; all other combinations 
are allowed. 

RPPAD, and RPPRM 
Pointers which must not be altered by programmer. 

The Special Real Time Operating System REPATCH service may be invoked 
by a FORTRAN program by defining a COMMON area as described above, 
moving the REPATCH control block address from the event control block 
to the RPCB field and then doing one of the following: 

a- If a REPATCH is to be executed without changes, set RPTYP to U or 
8 and CALL DPPPIF. 

b. If the REPATCH is to be changed prior to execution, set RPTYP = 0, 
CALL DPPPIF, make changes desired, set RETYP to a and CALL DPPPIF 
again. 

Users of this facility should be aware that only the supervisor portion 
of the PATCH parameters can be altered. The problem parameters cannot 
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be changed. All REPATCH control blocks must be returned to the system 
through a RPTYP = U or 8 ser¥ice request. 



Examples 1 and 2 show the various methods of using EEPATCH. The example 
for using EEPATCH service in FORTRAN use the folloving definitions of 
COMMON areas and constants: 

BLOCK DATA 

COMHON/RPATCH/REPMAC,REPRC, REPT YP ,TEPCB , REPTSK (2) , 
1REPEP (2) ,REPRTK (2) , REPQOE^REPVAL, REPECB,HEPRES (2) , 
1REPTCB, EEPFLG^SEPAD (3) ,REPPRM (3) 

LOGICAL REPTSK*4, REPEP*4, REPRTK*U,REPFLG*1 , REPAD*! 

INTEGER REPMAC*2/12AREPRC*2,REPTYP*4,REPCB*4,REPQaE*2, 
lRPVAL*2,RPECB*«*,RPRES*4,RPTCB*4,HPPRH*a 

COMM0N/WAIT/WTHAC,WTRC,WTECB 

INTEGER »TMAC*2/60/,HTRC*2/0/,WTECB/0/ 

END 

(The above comion areas should be repeated in the main program 
without data initialization. The following statements are in 
MAIN only.) 

LOGICAL QPOS*1/Z04 

Example .1 

This example shows the method for purging a REPATCH control block, 
should a work request fail to be executed. The example begins with 
the PATCH-WAIT which is notified that a REPATCH is needed. 

CALL DPPPIF (HTM AC) 
IF(WTRC.NE.68) GO TO 100 
REPCB=HTECB 
REPTYP=8 

CALL DPPPIF (REPMAC) 
200 CONTINUE 

Example 2 

This example demonstrates the method of altering a REPATCH control 
block- In this case, the REPATCH will place the work request in the 
front of the work queue. As in Example 1, this example begins with a 
PATCH-WAIT, 

100 CALL DPPPIF (WTM AC) 

IF (WTRC.NE. 68) GO TO 200 

RPCB=WTECB 

RPTYP=0 

CALL DPPPIF (RPMAC) 
CALL ORBIT (RPFLG,QPOS) 
WTECB=0 
RPTYP=U 

CALL DPPPIF (RPMAC) 
IF(RPRC.LT. 8) GO TO 100 

200 CONTINUE 



FQIIRMzEIIME Interface 

The PTIME service provides two different functions, return current time 
and PATCHes, issued on a time-queue basis. The following FORTRAN 
statements define the two different parameter lists for this service: 
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c 

C COMMON NAMED «PTIMR» — PARAMETER TABLE TOR PTIME 
COMMON/PTIMR/PTRMAC 

INTEGER*2 PTRMAC 
COMMON/PTIMR/PTRC 

INTEGER*2 PTRC 
COMMON/PTI MR/PTR TYP 

INTEGER*** PTRTYP 
COMMON/PTI MR/PTR TIM 

INTEGER*^ PTRTIM 
COMMON/PTI MR/PTR ARY 

INTEGER*a PTRARY 
C END OF COMMON NAMED •PTIMR* 



PTRMAC 

A half word binary value of U to identify to the interface routine the 
requested service. 

PTRC 

A half word binary value set to zero by the interface routine. 

PTRTYP 

A half word binary value identifying the PTIMR service being requested. 
For this parameter list it is always zero. 



PTRTIM 

A fullword binary field which will contain the current time of day in 
10-millisecond units when the interface routine returns. 



PTRARY 

A fullword field which will contain the address of the time array 
DPPCTIMA when the interface routine returns. 



C 

C COMMON NAMED 'PTIME — PARAMETER TABLE FOR PTIME 
COMMON/PTI ME/PTi MAC 

INTEGER*2 PTIMAC 
COMMON/PTIME/PTIRC 

INTEGER*2 PTIRC 
COMMON/PTI ME/PTITYP 

INTEGER*^ PTITYP 
COMMON/PTIME/PTISTR 

INTEGER*** PTISTR 
COMMON/PTIME/PTITVL 

INTEGER*** PTITVL 
COMMON/PTIME/PTIEND 

INTEGER*** PTIEND 
COMMON/PTIME/PTIPAT 

INTEGER*** PTIPAT 
COMMON/PTIME/PTIPRM 

INTEGER*** PTIPRM 
COMMON/PTIME/PTIS 

LOGICAL*! PTIS 
COMMON/PTIME/PTIP 

LOGICAL*! PTIP 
COMMON/PTIME/PTIE 

LOGICAL*! PTIE 
C END OF COMMON NAMED 'PTIME' 
C 



PTIMAC 

A half word binary value of *» to identify to the interface routine the 
requested service. 
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PTIHC 

A halfword binary field containing a binary number return code from 
the service. 

PTITYP 

A fulltford binary value identifying the requested PTIME service. 
Values may be 4, 8, or 12. If 4 , a PTIME queue element (PTQE) is 
created which controls the PATCHes issued according to the PTIME 
requested. Since the PTQE exists independently of the creating task 
and may be modified (8) or deleted (12) , the PTQE is referred to by 
task name, entry point name, and the PATCH ID number in the problem 
parameter list. Either task name or entry point name must be given 
for a modify (8) or delete (12). However, if only a task or entry 
point name is specified, all PTQEs with that name are deleted or 
modified. 

PTISTR 

A fullword binary value specifying the time in 10-millisecond units 
of the first PATCH. The flag bit in PTISTR defines the content of 
this field, according to the following table: 

X'04« — The first PATCH will be issued at current time plus the 
value of PTISTR. 

X'02' — The first PATCH will be issued when current time equals the 
value in PTISTR. If PTISTR is less than current time, the 
first PATCH will occur the next day- 

X'01' — The time of the first PATCH is calculated by assuming PTISTR 
contains the time of day, except that the value in PTITVL 
is added to PTISTR until that value is greater than current 
time. 

PTITVL* 

A fullword binary value specifying the interval in 10-millisecond 
units between successive PATCHes- 

PTIEND** 

A fullword binary value specifying when the PTQE is to be deleted. 
The flag bit in PTIE defines the content of this field. 

X»08' — PTIEND contains the count of the number of PATCHes to 

be issued by this PTQE. 

XI04'** — PTIEND contains a time value in 10-millisecond units, 
when added to current time equals the stop time. 

Xi02«** — PTIEND contains the stop time in 10-miliisecond units. 

XiQI'** — The stop time is czdculated by assuming PTIEND contains 
the time of day in 10-millisecond units except that the 
value in PTITVL is added to PTIEND until the value is 
greater than current time. 

♦All time units are in 10-millisecond units and must not exceed 2 4 
hours. 

♦♦Regardless of what value is calculated start time (see PTISTR above), 
a 24-hour value is added to the stop time until the stop time exceeds 
the start time. 

Note: If PTIEND and PTIE are zero, the PTIME is assumed infinite, and 
PATCHes will be issued until the PTQE is modified or deleted. 
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PTIPAT 

Contains the address of the supervisor portion of the PATCH parameters. 
The options provided will be used by PTIME to issue PATCHes based on 
the above time options. If the common area PATCH is used as defined 
in the FORTRAN PATCH Interface write-up, the parameter must point to 
PATASK(I). All information desired for the PATCH by PTIME must be 
supplied prior to CALLing the interface routine. RESTRICTION: Queue 
position of DPATCH (X»02» in PATFLG) is not permitted. 

PTIPRM 

Contains the address of the parameter list passed by PTIME's PATCH. 
See FORTRAN PATCH write-up for formats. 

Note; If this parameter list is greater than 8 bytes, the interface 
routine will move it to a GETMAIN area to be FREEMAINed when 
the PTQE is destroyed. 

PTIS 

A 1-byte logical field containing the flag which defines the content 
of PTISTR. See PTISTR above for flag definitions. 

PTIP 

A 1-byte logical field containing the flag which controls the kind of 
DPATCH which will be issued when the PTQE is destroyed. Flags at a 
PTIME delete (12) will override the flags when the PTQE was created 
(4) or last modified (8) . Only one flag may be set. 



x» 


08' — 


Task is deleted regardless of its condition. 




x» 


04' — 


Task is deleted when its work queue becomes empty. 




x» 


02' — 


Task is deleted only if its work queue is empty. 




x« 


01 ' — 


Task is deleted immediately or when the current work 
if executing, completes. Any work queue to the task 
posted as deleted. 


q ue ue , 

is 



PTIE 

A 1-byte logical field containing the flag which defines the content 
of PTIEND or zero. See PTIEND above for flag definitions. 

The PTIME facilities are invoked by CALLing DPPPIF with the properly 
completed parameter list. Examples 1 through H assumed the following 
FORTRAN statements about COMMON area, variables, and constants: 

BLOCK DATA 

COMMON/PATCH/PATBAC,PATPC,P ATPR M,PATASK (2) , 
1PATEP(2) ,PATNAM (2) , PATQ,PATV,PATECB,PATRES (2) , 
1PATCBX,PATF LG 

INTEGER P ATMAC*2/0/, PATRC*2/0/, PATPRM ,P ATQ* 2/1/, 
1PATV*2/0/,PATECB,PATRES,PATCBX 

LOGICAL PATASK*V' 'r1' '/rPATEP*t» 

1PATNAM*V' VrPATFLG*1 

COMMON/PTIME/PTIMAC,PATIRC, PTITYP, PTISTR, PTITVL, 
1PTIEND, PTIPAT, PTIPRM, PTIS, PTIP, PTIE 

INTEGER PTIMAC*2/4/,PTIRC*2/0/,PTITYP,PTISTR.PTITVL, 
1PTIEND, PTIPAT, PTIPRM, 

LOGICAL PTIS* 1, PTIP*1 , PTIE* 1 

COMMON/PTIME/PTRMAC,PTRC,PT RTYP,PTRTIM, PTRARY 
INTEGER PTRMAC*2/U/,PTRC*2/0/,PTRTYP/0/,PTRTIM, PTRARY 
END 
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(The above coomon areas should be repeated in the main program 
without data initialization. The folloifing statements are in 
MAIN only.) 

LOGICAL TOD*1,/Z02/,TN*4(2) /• TIME* , 'TEST'/r 
1TT*4(2) /'TTES* r 'T «/ 
LOGICAL QPOS* VZ04/»REL*1/Z01/,CNT*1/Z08/,ADJ*1/Z04/ 
LOGICAL Pa*VZ01/,DEL*1/Z01/ 
con MO N/PR OB L/PR BL NG , ID , PROS PI 
INTEGER PRBLNG*2,ID*2,PR0BPl*a 

Include the preceding common areas in MAIN area also. 

Example 1 

In Example 1, the program uses the COMMON PTIMR to obtain the current 
time. The current time is used to set the start time in PTISTR for 
PATCHes by PTIME, at current time plus 1 hour. The interval is set to 
1 hour, and the last PATCH is to occur 3 hours later. The PATCH 
parameters are set to create the task TIMETEST with a work queue length 
of 5, and a dispatching priority of 15 less than the PTIME task. The 
PATCH will execute program TTEST and delete it when the processing of 
each work request completes. The parameters are passed with a PATCH 
ID of 10. 

CALL DPPPIF (PTEMAC) 
P;PIPAT=IADDR(PATASK (1) ) 
PTIPRM=IADDR (PRBLNG) 
PTISTR=PTRTIM ♦ 360000 
CALL ORBIT(PTIS,TOD) 
PTITVL= 360000 
PTIEND=PTISTR * 1080000 
CALL ORBIT (PTIE, TOD) 
DO 100 1=1,2 
PATASK (I) =TN (I) 
100 PATEP (I) =TT (I) 
PATQ=5 
PATV=15 

CALL ORBIT (PATFLG, DEL) 

PRBLNG=a 

ID=10 

PTITYP=U 

CALL DPPPIF (PTIMAC) 
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Example 2 



In example 2, the PTQE built by Example 1 will be modified (TyPE=8) to 
start the PATCHes 15 seconds after this PTIWE is issued, the interval 
is changed to once a minute, and the stop time is changed to never end. 
The program will not be deleted when a work request is finished 
processing and the work request will be queued first. The PATCH ID 
will be changed to 5. Note that all parameters must be specified, as 
a modify acts as a replace. All COMMONS are initially as defined. 

PTITYP=8 

PTIPAT=IADDR(PATASK (1) ) 
PTIPRM=IADDR (PR BLNG) 
PTISTR=1500 
CALL ORBIT(PTIS,REL) 
PTITVL=6000 
DO 100 1=1,2 
PATASK (I) =TN (T) 
100 PATEP(I) 
PATQ=5 
PATV=15 

CALL ORBIT(PATPLG,QPOS) 

PRBLNG=4 

ID = 5 

CALL DPPPIF (PTIMAC) 



Example 3 

Example 3 shows the use of the adjusted time facility of PTIME, The 
first PATCH is to occur at 5 A.M., or within 30 minutes after the PTIME 
was issued and at 30-minute intervals for six times. The task is to 
be deleted immediately when the PTQE is destroyed. 



CALL ORBIT (PTIP,PU) 
PTISTR=1 80000 
CALL ORBIT (PTIS, ADJ) 
PTITVL=1 80000 
PTIEND=6 

CALL ORBIT (PTIE, CNT) 



PATCH parameters 



PROBLEM parameters 



PTITYP=4 

CALL DPPPIF(PTIMAC) 
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Example 4 



Example 4 shows the method for deleting a PTQE- Since the function of 
this PTIME service request is to locate the PTQE to be destroyed, only 
the parameters required to identify the PTQE need be given^ In this 
case, the task is to be DPATCHed as well. 

PTITYP=12 

CALL ORBIT(PTIP,P0) 
PTIPAT=IADDR (PA TASK (1) ) 
PTIPRM=IADDR (PRBLNG) 
DO 1001=1,2 
PATASK (I) =TN (1) 
100 PATEP (I) =TT (I) 
ID=10 

CALL DPPPIF (PTIMAC) 



FORTH ANzIIS SAGE Interface 

The MESSAGE service is used to cause a predefined message to be printed 
or displayed. The message must have been defined through the offline 
utility system using the DEFMSG macro. 

The following FORTRAN statements define the parameter list ^or this 

service: 
C 

C COMMON NAMED 'MESSAG' — PARAMETER TABLE FOE MESSAGE 

COMMON/MESSAG/MESM AC 

INTEGER«2 MESMAC 
COMMON/MESS AG/ME SRC 

INTEGER*2 MESRC 
COMMON/MESSAG/MESNUM 

INTEGER*2 MESNUM 
COMMON/MESS A G/MES ACT 

L0GICAL*1 MESACT 
COMMON/MESSAG/MESWT 

L0GICAL*1 MESWT 
COMMON/MESAG/MESRES 

INTEGER*a MESRES 
COMMON/MESSAG/MESDAT 

INTEGER*^ MESDAT 
COMMON/MESS A G/MESRTE 

INTEGER*2 MESRTE(8) 
COMMON/MESSAG/MESV AR 

INTEGER*^ MESVAR(IO) 
C END OF COMMON NAMED «MESSAG« 
C 

MESMAC 

A halfword binary value of 40 identifying to the interface routine 
the requested service. 

MESRC 

A halfword field containing a binary number return code from the 

MESSAGE service routine. See MESSAGE macro write-up for valid return 
codes. 

MESNOM 

A halfword binary value from 1 to 999 identifying the message 
requested. 
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MESACT 

A 1-byte logical field to be appended to the message number. I denotes 
information, A denotes action is required, and D denotes that a 
decision is required. Zero will indicate that the message definition 
default should be used. 

MESWT 

A 1-byte flag field using a X'08' to indicate the program's decision 
to WAIT for the message to be sent. A X'OO* implies NO WAIT. 

MESRES 

A fullword binary field reserved for the interface routine. 
MESDAT 

A fullword binary field containing the address of an aiea where the 
service routine will place the formatted message for use by the 
program. 

MESRTE 

An array of eight halfword binary numbers representing the devices on 

which the message will appear or will be printed. All unused entries 
must be zero or 255. Values must range from 1 to 25H» Entries with 

a zero will use the message definition default routing code. 

MESVAR 

An array of 10 fullwords containing addresses of message variables to 
be inserted into the message. All unused entries must be zero. Only 
consecutive non-zero entries will be used. 

The following example requests the MESSAGE service to output to route 
code (1) message number 37 with a variable text field of "END OF TEST." 
The message number will have an action coCe of "I" appended to identify 
the message as an advisory. The program will wait for the message to 
be transmitted. 

BLOCK DATA 
C FORTRAN MESSAGE EXAMPLE 

COMMON/MESS AG/H ESM AC, MESRC, MESN OM , M ES ACT, MESHT, MESRES , M ESD AT , 
1MESRTE(8) ,MESVAR(10) 

INTEGER MES MAC*2/^0/,MESRC* 2/0/, MESNOM* 2, MESRES, 
1MESDAT, MESR TE, MESVAR 

LOGICAL HESACT*1/100/,MESWT*1 

END 

(The above COMMON areas should be repeated in the main program 
without data initialization. The following statements are in 
MAIN only.) 

LOGICAL A*4 (4)/'bEND» , • bOF b« , ' TEST ' , bbb « /# ACT* 1/' I ' /r 

WT*1/Z8 0/ 

MESNnM=37 

MES ACT=ACT 

CALL ORBIT(MESWT,WT) 

MESRTE(I) =1 

MESVAR(I) =IADDR (A(1)) 

MESVAR (2) =0 

CALL DPPPIF (MESMAC) 



FORTRAN-RECORD Interface 

The RECORD facility provides a method for writing data to a sequential 
data set. The data can be retrieved at a later time for offline 
processing (see section on data playback) . The following FORTRAN 
statements define the parameter list for this service: 
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c 

C COMMON NAMED 'RECORD* — PARAMETER TABLE FOR RECORD 
COMMON/RECORD/RECM AC 

INTEGER*2 RECMAC 
COMMON/RECORD/RECRC 

INTEGER*2 RECRC 
COMMON/RECORD/RECCNT 

INTEGER*U RECCNT 
COMMON/RECORD/RECDAT 

INTEGER*^ RECDAT 
COMMON/RECORD/RECID 
INTEGER*2 RECID 
C END OF COMMON NAMED » RECORD' 
C 

RECMAC 

A halfword binary value of 56 identifying to the interface routine 
the requested service. 

RECRC 

A halfword field containing a binary number return code from the RECORD 
service routine. See RECORD macro Wtite-up for valid return codes. 

RECCNT 

A fullword binary field containing the number of data bytes to be 
recorded. A maximum value of 65 535 may be specified. 

RECDAT 

The address of the data to be recorded. 

RECID 

A halfword binary number from 1 to ^095 which identifies the data 
being recorded. 

The following example uses RECORD to write the entire 100 fullwords 
from array ANNUAL with an ID OF 100. 

C FORTRAN RECORD EXAMPLE 
BLOCK DATA 

COM MON/RECORD/RECMAC,RECRC,RECC NT rRECDATr RECID 

INTEGER RECMAC* 2/56/, RECRC* 2/0/, RECCNT,RECD AT, RECID*2/0/ 

END 

(The above COMMON areas should be repeated in the main program 
without data initialization. The following statements are 
in MAIN only.) 

INTEGER ANNUAL(IOO) 



RECCNT=400 

R EC DAT=IADDR (ANNUAL (1) ) 

RECID=1 00 

CALL DPPPIF (RECMAC) 



FORTRAN-GET ARRAY/PUT ARRAY Inter fa ce 

This FORTRAN interface provides the programirer the facilities of the 
GETARRAY and PUTARRAY services. The following FORTRAN statements define 
the interface parameter list: 
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c 

C COMMON NAMED' ARRAY' — PARAMETER TABLE FOR GETARRAY AND PUTARRAY 
COMMON/ARSAY/ARH AC 

TNTEGER*2 ARMAC 
COMMON/ARRAY/ARRC 

INTEGER*2 ARRC 
COMMON/ARR AY/ARNAM 

INTEGER*^ ARHAM 
COMMON/ARR AY/AR ARE A 

INTEGER*^ ARAREA 
COMMON/ARR AY/ARN ADD 

INTEGER*2 ARNADD 
COMMON/ A.RR AY/AR ADD 

INTEGER*2 ARADD 
COMMON/ARR AY/ART YPE 

INTEGER*2 ARTYPE 
C END OF COMMON NAMED 'ARRAY' 
C 

ARMAC 

A halfword binary value of 16 identifying the service required "to the 
interface routine. 

ARRC 

A halfword binary field containing the return code from the array 

service routine. See GETARRAY and POTARRAY macro write-ups for 
possible values. 

ARNAM 

A fullword field containing the address of one of the following based 
on the specifications implied by the value of ARTYPE- 

a. If ARTYPE specifies the 'NAME LIST* option for ARNAM (s/se Figure 
2-21) , then ARNAM contains the address of a list of 8-character 
array names followed by an X'FF' after the last name where the next 
name would start. ARNADD contains the value to be added to the 
list address to locate the next array name. 



NAME LIST 



0 NAME I 



8 NAME 2 



b. If ARTYPE specifies 'NUMBER LIST' then ARNAM contains the address 
of halfword binary array numbers followed by a X'FF' after the last 
array number where the next number would start. ARNADD contains 
the value to be added to the list address to locate the next array 
number in the list. 



NUMBER LIST 



0 1ST NUMBER 

2 2ND NUMBER 



c. If ARTYPE specifies 'ADDRESS 
of a list of array addresses 
execution. The list must be 



LIST', then ARNAM conterins the address 
as returned from a previous GETARRAY 
terminated by a fullword binary value 



APPLICATION SERVICES 2-131 



of -1 after the last array address where the next address would be 
located. ARNADD contains the value to be added to the list address 
to locate the next array address. 



ADDRESS LIST 4 6 8 10 



0 


FLAG 


AdST ARRAY) 


NO. BLKS 


SIZE 


NO. ITEMS 


+ARADD 


FLAG 


A(2ND ARRAY) 


NO. BLKS 


SIZE 






FFFFFFFF 









This list is the same as returned as the find list specified below 
with the addition of the termination flag which must be added by the 
user. 

ABAREA 

A fullword field containing the address of one of the following based 
on the specifications implied by the value of ARTYPE. 

a. If ARTYPE specifies the "DATA LIST' option for ARAREA (see Figure 
2-21) , then ARAREA contains the address of a list of addresses into 
or from which the data of the specified arrays (see ARNAM above) 
is to be moved. ARADD contains the value to be added to the list 
address to locate the next data area address in the list. 



DATA AREA ADDRESS LIST 



ARADD*! 
ARADD*2 



AdST DATA AREA) 



A(2ND DATA AREA) 



A(3RD DATA AREA) 



b. If ARTYPE specifies 'FIND LIST', then ARAREA contains the address 
of a list of 10-byte fields to be filled: a flag byte (see GETARRAY 
macro write-up), a 3- byte array address, a halfword block count, 
a halfword array size or block size, and a halfword item count. 
ARADD contains the value to be added to the list address to locate 
the next entry in the list. The minimum value for ARADD under this 
option is 8, in which case, the item count halfword will not be in 
the list. 



FIND LIST 
1 4 6 8 



0 


FLG 


ARRAY ADDR 


NO. BLKS 


SIZE 


NO. ITEMS 


ARADD*1 


FLO 


ARRAY ADDR 


NO. BLKS 


SIZE 


NO. ITEMS 


ARADD*2 


FLG 


ARRAY ADDR 


NO. BLKS 


SIZE 


NO. ITEMS 
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c. If ARTYPE of addresses specifies 'SPEC LIST', the AFAPEA contains 
the address of a list of areas to be filled in by the service 
routine. Each area will receive a 16-byte field for each item in 
the array. These 16-byte fields will contain an 8-byte item name, 
a 1-byte item length, a 1-byte data type, a halfword array 
displacement to the start of the item, a halfword array ID, and a 
halfword number identifying the number of identical and seguential 
items defined by this entry- ARADD contains the value to be added 
to the list address to locate the next 16-byte field. 



ARRAY SPECIFICATIONS LIST 

8 9 10 12 14 



0 


ITF.M NAME 


LNG 


TYPE 




DISP. 


AID 


REPT 


16 


ITEM NAME 


LNG 


TYPE 


DISP 


AID 


REPT 


32 


ITEM NAME 


LNG 


TYPE 


DISP 


AID 


REPT 



ARNADD 

A halfword value added to ARNAME to locate the next entry in the list. 
A value must be specified. 

ARADD 

A halfword value added to ARAREA to locate the next entry in the list. 
A value must be specified. 

ARTYPE 

A halfword binary value specifying the array service options selected. 
The values (given in the tables below) identify the contents of ARNAME 
and ARAREA, either a GETARRAY or PUTARRAY, the array (i.e., DATALISI, 
ADDRLIST, or SPECLIST) , and the desired protection for GETARRAYs 
(PROTECT or RISK) . 

DATALIST 

Specifies that the contents of the arrays are to be returned (GETARRAY) 
or updated (PUTARRAY). 

ADDRLIST 

Specifies that a »^FIND LIST' entry is to be completed for each array 
name or number in the list. This option is valid for virtual storage 
resident arrays only. 

SPECLIST 

Specifies that a 'SPEC LIST' entry is to be completed for each item 
of each array name or number in the list. 

PROTECT 

Specifies that the array service will be locked during processing to 
prevent changes from altering results. 

RISK 

Specifies that the array service will be processed regardless of the 
possibility of parallel processing changing array content. 
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ARNAM 


ARAREA 


SERVICE 
REQUESTED 


PROTECTION 
REQUESTED 


ARTYPE 
VALUE 


A(NAME LFST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


16 


A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


17 


A(NAME LIST) 


A(SPEC LIST) 


SPEC LIST 


PROTECT 


20 


A(NAME LIST) 


A(SPEC LIST) 


SPEC LIST 


RISK 


21 


A(NAME LIST) 


A(FrND LIST) 


ADDR LIST 


PROTECT 


34 


A(NAME LIST) 


A(FIND LIST) 


ADDR LIST 


RISK 


35 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


48 


A(ADDR LIST) 


A(DATA LIST.) 


DATA LIST 


RISK 


49 


A(NUMBER LIST) 


A(DATA LIST) 


DATA LIST 


PROTECT 


80 


A(NUMBER LIST) 


A(DATA LIST) 


DATA LIST 


RISK 


81 


A(NUMBER LIST) 


A(SPEC LIST) 


SPEC LIST 


PROTECT 


84 


A(NUMBER LIST) 


A(SPEC LIST) 


SPEC LIST 


RISK 


85 


A(NUMBER LIST) 


A(FIND LIST) 


ADDR LIST 


PROTECT 


98 


A(NUMBER LIST) 


A(FIND LIST) 


ADDR LIST 


RISK 


99 



•^igure 2-21 . GETARRAY Service 



A(NAME LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


128 


A(ADDR LIST) 


A(DATA LIST) 


DATA LIST 


N/A 


144 


A(NUMBER LIST 


A(DATA LIST) 


DATA LIST 


N/A 


176 



Figure 2-22. PUTARRAY Services 

The GETARRAY/PUTARR AY services are invoked by CALLing DPPPIF with the 
properly completed parameter list. 

The following example shows the use of the array services in locating 
the array reading in the item specifications, reading the entry 
array into FORTRAN core, and updating the array. 

BLOCK DATA 
C FORTRAN GET/PDT-ARR AY EXAMPLE 

C 

COMMON/ARRAY/ARMAC^ARRC, ARNAM, ARAREA, ARNADD, ARADD, ARTYPE 
INTEGER ARMAC*2/0/, ARRC*2/0/, ARNAM, ARAREA, ARNADD*2/8/, 
1ARADD*2/4/, ARTYPE*2/16/ 
END 

(The above COMMON areas should be repeated in the main program 
without data init ia liztion. The following statements 
are in MAIN only. ) 



2-134 



Description and Operation Manual 



COMMON/AR AY/ANA ME (2) ,AEND,AFIND (6,2) , ACORE 

INTEGER END*4,AFIND*2, ACORE *4 

LOGICAL ANAHE'«'4 

COM MO N/AITM/T NAME (16,255) 

LOGICAL INAME*1 

EQOIVALENCE (AFIND(1,1) ,ADRA(1,1) 
INTEGER ADRA(3,2) 

EQaiVALENCE (INAME(lrl) ,SPEC(1,1)) 
INTEGER SPEC*2(8,255) 
COMMON/ AREA/DAT A (16, 255) 
LOGICAL DATA*1 

LOGICAL A*t»(2)/«B •/ 

ANAME(1) =A(1) 

ANAME(2)=A(2) 

AEND=1 

ARNAM=IADDR (ANAME(1)) 
ARNADD=8 

ARAREA=IADDR(AFIND(1,1) ) 

ARADD=1 2 

ARTYPE=35 
C BUILD FIND LIST 

CALL DPPPIF (ARMAC) 

ACORE = I ADDR (INAME (1 , 1) ) 

ARAREA=IADDR (ACOBE) 

ARADD=U 

ARTYPE=21 
C BUILD ITEM SPEC LIST 

CALL DPPPIF (ARMAC) 

ACORE = IADDR (DATA(1, 1) ) 

ARTYPE=16 
C READ ARRAY 

CALL DPPPIF (ARMAC) 

ARTYPE=128 
C UPDATE ARRAY 

CALL DPPPIF (ARM AC) 

FORTRAN-GETITEM/P UTITEH I titer face 

This FORTRAN interface provides the programmer the facilities of the 
GETITEM and PUTITEM services. The following FORTRAN statements define 
the interface paramater list: 

C 

C COMMON NAMED • I TE M' —PARAMETER TABLE FOB GETITEM AND PUTITEM 
C0MM3N/ITEM/ITMAC 

I^ITEGEf(*2 ITMAC 
COMMDN/ITEH/ITMRC 

INTEGER*2 ITMRC 
COMMON/ITEM/ITMN AM 

INTEGER*4 ITMNAM 
COMMON/ITEM/ITMDAT 

INTEGER*4 ITMDAT 
COMMON/ITEM/ITMN AD 

INTEGER*2 ITMNAD 
COMMON/ITEH/ITMDAD 

INTEGER*2 ITMDAD 
COMMON/ITEM/ITMTYP 

INTEGER*2 ITMTYP 
C END OF COMMON NAMED 'ITEM* 
C 

ITMiC 

A talfword binary value of 20 identifying the service required to the 
interface routine. 
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ITMRC 

A half word field containing a binary number return code froB the item 
service routine. See GETITEM and POTITEM macro write-ups for possible 
values. 

ITMNAM 

A fullword field containing the address of one of the following based 
on the specifications implied by the value of ITMTYP. 

a- If ITMTYP specifies »NAMELIST», the ITMNAM contains the address of 
a list of 8-character item names followed by a X*f¥* after the last 
name where the next name would start. 

ITMNAD contains the value to be added to the list address to locate 
the next item name. 



NAME LIST 



+ITMNAD 
+ITMNAD*2 



NAME 1 



NAME 2 



F F 



b. If ITMTYP specifies 'ADDRESS LIST', the ITMNAM contains the address 
of a list of item addresses as returned from a previous execution. 
The list must be terminated by a fullword of -1 where the next 
address would be in the list. ITMNAD contains the value to be 
added to the list address to locate the next item address in the 
list. 



ADDRESS LIST 



0 

+ITMNAD 
+ITMNAD*2 



LENGTH 


A(ITEMA) 


LENGTH 


AdTEMB) 


FFFFFFFF 



ITMDAT 

A fullword field containing the address of one of the following based 
on the specifications implied by the value of ITMTYP. 

a. If ITMTYP specifies 'DATA LIST', the ITMDAT contains the address 
of a data area into or from which data is moved- ITMDAD contains 
the value to be added to the data area addresss to locate the area 
for the next item. If ITMDAD is zero, the item length is used to 
locate the next item data area. 

b. If ITMTYP specifies ' ADDR LIST', the ITMDAT contains the address 
of a list of t»-byte entries into which an item length and address 
is stored for each item specified in the 'NAME LIST.' The list must 
contain room for one more entry to allow the service routine to 
store an end of list X'FF,' ITMDAD contains the value to be added 
to the list address of locate the next entry. 



ADDRESS LIST 



LENGTH 


ITEM ADDRESS 


LENGTH 


ITEM ADDRESS 


FF 


FF FF FF 
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c. If ITMTYP specifies •SPECLIST*, the ITMDAT contains the address of 
a list of 4-byte entries each containing the item length, flags 
identifying data type, and an array displacement to the first byte 
of the iten. ITHDAD contains the value to be added to the list 
address of locate the next entry. 



Item Specification List 

8 9 10 12 14 16 



ITEM NAME 


LNG 


TYPE 


DISP. 


AID 


REPT 


ITEM NAME 


LNG 


TYPE 


DISP. 


AID 


REPT 


ITEM NAME 


LNG 


TYPE 


DISP. 


AID 


REPT 



ITMNAD 

A halfword binary value added to the list address in ITMN&M to locate 
the next entry A value must be A value must be specified. 

ITMDAD 

A halfword binary value added to the list address in ITMDAT to locate 
the next entry. A value must be specified unless ITMTYP specifies 
•DATA LIST', in which case zero may be used, 

ITMTYP 

A halfword binary number specifying the item service options selected. 
The values (given in the figures 2-23 and 2-2U) identify the kind of 
service (i.e., DAT ALIST, ADDHLIST , or SPECLIST) , if it is a GETITEM or 
POTITEM, and if GETITEM is protected (PROTECT or RISK). A value must 
be specified. 

DATALIST 

Specifies the content of the item is to be moved to or updated from 
the data area. 

ADDRLIST 

Specifies the item 'ADDRESS LIST* is to be built for each named item. 
SPECLIST 

Specifies the item 'SPECIFICATION LIST* is to be built for each named 
item. 

PROTECT 

Specifies the GETITEM service will ensure data integrity during 
processing. 

RISK 

Specifies the GETITEM service will process the request regardless of 
the possibility of parallel processing updating the content of the 
named item (s) . 



Note: DATALIST and ADDRILIST are invalid service requests for direct 
access resident arrays. 
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ITMNAM 


ITMDAT 


SERVICE 
REQUESTED 


PROTECTION 
REQUIRED 


ITMTYP 
VALUE 


A(NAME LIST) 
A(NAME LIST) 
A(NAME LIST) 
A(NAME LIST) 
A(NAME LIST) 
A(NAME LIST) 
A(ADDR LIST) 
A(ADDR LIST) 


A(DATA LIST) 
A(DATA LIST) 
A(ADDR LIST) 
A(ADDR LIST) 
A(SPEC LIST) 
A(SPEC LIST) 
A(DATA LIST) 
A(DATA LIST) 


DATA LIST 
DATA LIST 
ADDR LIST 
ADDR LIST 
SPEC LIST 
SPEC LIST 
DATA LIST 
DATA LIST 


PROTECT 

RISK 
PROTECT 

RISK 
PROTECT 

RISK 
PROTECT 

RISK 


136 
137 

I JO 

139 
140 
141 
152 
153 


Figure 2-23. 


GET ITEM Services 






A(NAME LIST) 
A(ADDR LIST) 


A(DATA LIST) 
A(DATA LIST) 


DATA LIST 
DATA LIST 


N/A 
N/A 


184 
200 


Figure 2-24 . 


PUTITEil Services 







The GETITEM/PUTITEM services are invoked by CALLing DPPPIF with a 
properly completed parameter list. 
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The following example will use the item service to obtain the addresses, 
specifications, and data for a list of five items from the sane array 
and update them in the array. 

BLOCK DATA 
C FORTRAN GET/PUT-ITEM EXAMPLE 

COMMON /ITEM/ I TM AC ,ITMRC ,1 TMNA IT MD AT , ITMN AD, ITMD AD, 

1ITMTYP 

INTEGER ITMAC*2/20/,ITMRC*2/0/,ITMKAH,ITMDAT, ITMNAD*2, 
1ITMDAD*2,ITMTYP*2/0/ 
COMMON /AREA/ DATA(16,5) 
L0GICAL*1 DATA 
COMMON /N/ NAME (2,5) , END 
INTEGER END/-1/ 

LOGICAL*a NAME/1B01 •,' •,»B03 •,• «,'B05 'r 
1«B07b», 'bbb', 'BOeb* ,«bbbbV 

END 

(The above common areas should be repeated in the main program 
without data initialization. The following statements are 
in MAIN only.) 

INTEGER ADR (6) 
L0GTCAL*1 LNG(U,5) 
ITMNAM=LADDR (NAME (1,1)) 
ITMNAD=8 

ITMDAT=IADDR (ADR (1) ) 

ITMDAD=a 

ITMTYP=139 
C FIND ARRAY ITEMS 

CALL DPPPIF (ITMAC) 

ITMDAT=IADDR (LNG (1, 1) ) 

ITMTYP= 1U1 
C GET ITEM SPECS 

CALL DPPPIF (ITMAC) 

ITMNAM=IADDP(ADP(1) ) 

ITMNAD=U 

ITMDAT=IADDR (DATA (1,1)) 

ITMDAD=16 

ITMTYP=152 
C READ ITEMS BY ADDRESS 

CALL DPPPIF (ITMAC) 

ITMTYP=200 
C UPDATE ITEMS BY ADDRESS 

CALL DPPPIF (ITMAC) 



IQRTRMlGETBLOCK/POTBLOCK Interface 

This FORTRAN interface provides the programmer the facilities of the 
GETBLOCK and PDTBLOCK services. The following FORTRAN statements define 
the interface parameter list: 
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c 

C COMMON NAMED » BLOCK ' aPARAMETER TABLE FOR GETBLOCK AND 
POTBLOCK 

COMMON/BLOCK/BLKMAC 

INTEGER *2 BLKMAC 
COMMON/BLOCK/BLKRC 

INTEGER*2 BLKRC 
COMMON/BLOCK/BLKNAM 

INTEGER*4 BLKNAH 
COMMON/BLOCK/BLKDAT 

INTEGER*^ BLKDAT 
COMMON/BLOCK/BLK ADD 

INTEGER*2 BLKADD 
COMMON/BLOCK/BLKTYP 

INTEGER*2 BLKTYP 

C END OF COMMON NAMED 'BLOCK* 
C 

BLKMAC 

A halfword binary value of 24 identifying the service requested to 
the interface routine. 

BLKRC 

A halfword field containing a binary number return code from the 
blocked array service routine. Zero indicates successful completion 
while any non-zero indicates unsuccessful completion. 

BLKNAM 

A fullword field containing the address of one of the following based 
on the specifications implied by BLKTYP- 

a. If BLKTYP specifies »NAME LIST* the BLKNAM contains the address of 
a list of 8-character array names followed by a X*FF' in the first 
byte after the last name where the next name would start- 

NAME LIST 



0 NAME 



8 NAME 



16 FF 



b. If BLKTYP specifies 'NUMBER LIST', the BLKNAM contains the address 
of a list of halfword array number followed by a X'FF' in the first 
byte after the last number where the next number would start. 



NUMBER LIST 



0 NUMBER 



2 NUMBER 



4 FF 
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BLKADD contains the value to be added to the list address to locate 
the next entry. 



DATA AREA LIST 



FLG 


DATA AREA 


BLK. NO. 


FLG 


DATA AREA 


BLK. NO. 


FLG 


DATA AREA 


BLK. NO. 



PLS A 1-byte flag field. A X*UO' indicates the last data area 
and block number for a specified array but not the end of the list. 
A X'80' indicates the last entry for the last array and the end of 
the list. A X»00' should appear in all other entries. 

DATA AREA A 3-byte address of the area into or from which the 
specified array block is moved, 

BLK. NO. — A half word binary number specifying the array block being 
mov ed . 

BLKADD 

A halfword binary value added to the contents of BLKDAT to locate the 
next entry in the list. If zero, a value of 6 is assumed. 

BLKTYP 

A halfword binary value specifying the blocked array service options 
selected. The value (given in the tables below) identify the contents 
of BLKNAM and if it is a GETBLOCK with or without protection (PROTECT 
or RISK) or a PUTBLOCK. 



BLKNAM 


BLKDAT 


PROTECTION 
REQUESTED 


BLKTYP 
VALUE 


A(NAME LIST) 
A(NUMBER LIST) 

A(NAME LIST) 
A(NUMBER LIST) 


A(DATA LIST) 
A(DATA LIST) 
A(DATA LIST) 
A(DATA LIST) 


RISK 

RISK 
PROTECT 
PROTECT 


4 
6 
12 
14 


Figure 2-25. 


GETBLOCK Services 




A(NAME LIST) 
A(NUMBER LIST) 


A(DATA LIST) 
A(DATA LIST) 


N/A 
N/A 


5 
7 



Figure 2-26. PUTBLOCK Services 

The GETBLOCK/PUTBLOCK services as invoked by calling DPPPIF with a 
properly completed parameter list. 
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The following example Hill execute a GETBLOCK for block number 5 from 
array BLK1 and BLOKB, Then the blocks are written out to their 
respective arrays. 

BLOCK DATA 
C FORTRAN GET/PUT-BLOCK EXAMPLE 

COMMON /BLOCK/ BLKM AC, BLKRC ,BLK NAM, BLKD AT, BLK ADD, BLKTYP 
INTEGER BLKMAC*2/24/, BLKRC* 2, BLKN AM , BLKD AT, BLKADD*2, 
1BLKTYP*2 
COMMON /N/ NAME (2,2) , END 

LOGICAL*^ NAME/'BLKI' , ' »,*BLOK»,»B »/ 

INTEGER *2 END/- 1/ 
END 

(The above COMMON areas should be repeated in the main program 
without data initialization. The following statements are in 
MAIN only.) 

COMMON /LIST/ AREA(2,2) 
INTEGER*^ AREA 

EQaiVALENCE (AREA(1, 1) ,NUM (1,1) 
INTEGER*2 N0M(i*,2) 
COMMON /BLK/ DATA (256, 2) 
L0GICAL*1 DATA 

L0GICAL*1 NEXT/Z40/,STOP/Z8 0/ 
AREA (1 ,1) =IADDR(DATA(1 ,1)) 
NUM (3,1) =5 

CALL ORBIT(AREA (1 ,1) ,NEXT) 
ARE A (1, 2) =IADDR (DATA(1, 2) ) 
NUM (3,2) =5 

CALL ORBIT (AREA (1,1) , STOP) 
BLKNAM=IADDR(NAME (1,1)) 
BLKDAT=IADDR( AREA (1,1)) 
BLKADD=8 
BLKTYP=12 

C READ BLOCK 5 OF ARRAYS BLK1 and BLOKB 

CALL DPPPIF (BLKMAC) 

BLKTYP=5 
C OPDATE BLOCK 5 IN ARRAYS 

CALL DPPPIF (BLKMAC) 



FORTRANnGETLOG Interface 

This FORTRAN interface provides the programmer the facilities of the 
GETLOG service. The following FORTRAN statements define the interface 
parameter list. 
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c 

C COMMON NAMED 'GETLOG* PARAMETER TABLE FOR GETLOG 

C 

COMMON/GETLOG/GETMAC 

INTEGER*2 GETMAC 
COMMON/GETLOG/GETRC 

INTEGER*2 GETEC 
COMMON/GETLOG/GETYPE 

INTEGER*2 GETYPE 
COMMON/G ETLOG/GETNO 

INTEGER GETN0*2 
COMMON/G ETLOG/GETD AT 

INTEGER*^ GETDAT 
COMMON/GET LOG/GETCPY 

INTEGER*'! GETCPY 
COMMON/GETLOG/GETHD 

INTEGER*^ GETHD 
COMMON/G ETLOG/GETN AM 

INTEGER*4 GETNAM 
C END OF COMMON NAMED 'GETLOG* 
C 

GETMAC 

A halfword value of 48 identifying the service required to the 
interface routine. 

GETRC 

A halfword binary field containing a binary number return code from 

the GETLOG service routine. See GETLOG macro write-up for possible 
values. 

GETYPE 

A halfword flags field indicating the requested options to the GETLOG 
service routine. Bits are numbered 0 to 7. 

Bits 0, 1, 

3, 5, and 77 — Reserved. 
Bit 2 — See GETHD. 

Bit 4 — If on, the GETLOG service routine protects the data 

content across the service request. 

Bit 6 — If on, GETNO contains the array number of the log 

copy being read. If off, GETNAM contains the address 
of the array name. 

Byte 2 — Reserved. 

GETNO 

A halfword field containing the number of the array whose log copy is 
being read- Valid only if Bit 6 of GETYPE is on. If bit 6 is off, 
this field is zeroed by the interface routine. 

GETDAT 

A fullword field containing the address of the data area into which 
the log copy requested will be placed. The area must be large enough 
to hold the entire array and its 24-byte log header. 

GETCPY 

A fullword binary number used to determine which copy of a logged 
array, relative to the GE^HD parameters, will be retrieved from the 
log data set. 



APPLICATION SERVICES 2-143 



GETHD 

A fullword field containing one of the following based on Bit 2 in 
GETYPE 

a. If Bit 2 is on, then GETHD contains the address of a 2U-byte log 
header identifying the relative starting point to determine which 
copy of the array will be retrieved from the log data set. 

b. If Bit 2 is off and GETHD is zero, then the current copy becomes 
the relative starting point. 

c. If Bit 2 is off and GETHD is non-zero, then GETHD contains the 
address of a 6-byte time and day field. The first 4 bytes will 
contain a time in 10- millisecond units. The last two bytes contain 
a binary value from 1 to 366, representing the day of the year. 
This time and day will be used as a comparison value to establish 

a relative starting point to determine which copy of the array will 
be retrieved from the log data set, 

GETNAM 

A fullword address of the name of the named array, a log copy of which 
is being requested. Valid only if BIT 6 of GETYPE is off. 

The GETLOG service is invoked by CALLing DPPPIF with a properly 
completed parameter list. 

The following example will GETLOG the previous logged copy of array B 
referenced from the current copy. 

BLOCK DATA 
C FORTRAN GETLOG EXAMPLE 

C 

COHMON/GETLOG/GETMAC, GETRC, GETYPE,GETNO, GETDAT, , GETCPY, 

1GETHD,GFTNAM 

INTEGER GET MAC* 2/48/, GETRC* 2/0/, GETYPE* 2/0/, GET N0*2, 
1 GET DAT, GETCPY ,G ETHD, GETNAM 
END 

(The above common areas should be repeated in the main program 
without data initialization. The following statements 
are in MAIN only.) 

COMMON/LOG /HEADR (12) ,LDATA(24) 
INTEGER*2 HEADR, LDATA 
LOGICAL A*4 (2) /'B • , • '/ 



GETDAT=IADDR (HEADR (1) ) 
GETNAM=IADDR(A( 1) ) 
GETCPY=-1 

CALL DPPPIF (GETMAC) 
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FORTRAH- POTLOG Interface 

This FORTRAN interface provides the programmer the facilities of the 
PUTLOG service. The following FORTRAN statements define the interface 
parameter list. 



C COMMON NAMED 'PUTLOG' PARAMETER TABLE FOR PUTLOG 

C 

COMMON/PUT LOG/PUTM AC 

INTEGER+2 PUTMAC 
COWMON/fUTLOG/PUTRC 

INTEGER*2 PUTRC 
COMMON/PUTLOG/PUTNAH 

INTEGER*t| PUTNAM 
COMMON/PUTLOG/PUTHD 

INTEGER*4 PUTHD 
COMMON/PUTLOG/PUTYPE 

INTEGER*2 PUTYPE 
COHMON/PUTLOG/PUTBLK 

INTEGER*2 PUTBLK 

C 

C END OF COMMON NAMED 'PUTLOG* 

C 

PUTMAC 

A halfword binary value of U4 ider-tifying the requested service to 
the interface routine, 

PUTRC 

A half word binary field containing a binary number return code from 
the PUTLOG service routine. See PPUTLOG macro write-up for possible 
values. 

PUTNAM 

A fullword containing the address of one of the following based on 
Bits 5 and 6 in PUTYPE. 

a. If Bits 5 and 6 are zero (where bits in a byte are numbered 0 to 
7), then PUTNAM contains the address of an 8-character array name. 

b. If Bit 5 is off and Bit 6 is on, then PUTNAM contains the address 
of a halfword containing an array number. 

c. If Bit 5 is on and Bit 6 is off, then PUTNAM contains the address 
of a list of 8-character array names* The first byte past the last 
valid entry must be set to X'FF* to indicate the end of the name 
list. 



NAME LIST 



0 NAMEI 



8 NAME2 



16 FF 



d. If Bits 5 and 6 are on, then PUTNAM contains the address of a list 
of halfword binary array numbers. The first byte past the last 



APPLICATION SERVICES 2-145 



valid entry must be set X»FF' to indicate the end of the number 
list. 



NUMBER LIST 



0 1ST NUMBER 



2 2ND NUMBER 



4 FF 



PDTHD 

A fullword field containing the address of one of the following based 
on Bits 2 and 3 in PUTYPE. 



a. If Bits 2 and 3 are both off, then PDTHD must be zero. 

b. If Bit 2 is on and Bit 3 is off, then POTHD contains the address 
of an array logging header. Information in this logging header 
will identify the copy of the array which is to be replaced in the 
log data set. The logging header is a 2't-byte control block which 
precedes the array, both as the array exists in virtual storage 
and as it is written to the logging array. The logging header 
which was retrieved as part of a previous GETLOG may be used to 
replace that copy in the log data set. 

c. If Bit 2 is off and Bit 3 is on, the POTHD contains the address of 
a user-constructed list of block numbers and storage addresses. 
The latest log copy will be modified. However, only the log block 
corresponding to the VS resident block specified will be updated. 



FLG DATA ADDRESS BLK. NO 



FLG — A 1-byte flag field. 

X'40' — Indicates the last entry to be processed for a 

particular entry in the name or number list. 

X'80» — Indicates the last entry in the data list, 

DATA ADDRESS ~ Ignored. 

BLK NO. — The number assigned to the data block to be updated. 
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EXAMPLE: BLKLIST and Name List 



NAME LIST 



BLKLIST 





A(AREA) 


HT 




A(AREA) 


H'5' 


X'40' 


A(AREA) 


H'lO' 


X'40' 


A(AREA) 


HT 




A(AREA) 


H'2' 


X'80 


A(AREA) 


H'3' 



FIRSTbbfe 



SECONDbbb 



THlRDbbb 



FF 




PUTYPE 

A 2-byte flags field specifying the selected options. 
Bits 0 and 1 — Reserved, 
Bits 2 and 3 — See PUTHD. 

Bit 4 — If on, the PUTLOG is protected while processing- 

Bits 5 and 6 — See POTNAM, 

Bit 7 — Must be on to indicate a PUTLOG. 

Byte 2 — Reserved, 

PUTBLK 

If flag bit 2 is off and Bit 3 is on, then the half word value in this 
field is used to increment the address in PUTHD, 

The PUTLOG service is invoked by CALLing DPPPIF with the properly 
completed parameter list. 

The following example logs the array B as the current log copy. 

BLOCK DATA 
C FORTRAN PUTLOG EXAMPLE 

C 

C0MM0N/PUTLOG/PUTMAC,PUTRC, PUTNAM, PUTHD, PUTYPE, 
1 PUTBLK 

INTEGER PUTMAC*2/Ua/,PUTRC*2/0/, PUTNAM^ PUTH D, PUTYPE*2/0/, 

1 PUTBLK *2/0/ 

END 

(The above COMMON areas should be repeated in the main program 
without data initialization. The fo? ""owing statements 
are in MAIN only.) 

LOGICAL *4 A(2)/««B •/ 
LOGIC AL*1 PUT/Z01/ 
CALL ORBIT (PUTYPE, PUT) 
PDTNAM=IADDR (A( 1) ) 
CALL DPPPIF (PUTMAC) 
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F0BTR4N-I)IJ.M.PI.QG Interface 



This FORTRAN interface provides the programmer the facilities of the 
DUMPLOG service. The following FORTRAN statements define the interface 
parameter list: 



C COMMON NAMED 'DUMPLG' — PARAMETER TABLE FOR DOMPLOG 
COMMON/DOMPLG/DPLHAC 

INTEGER*2 DPLMAC 
COMMON/DUMPLG/DPLRC 

INTEGER*2 DPLRC 
COMMON/DOM PL G/DPL^YP 

INTEGEF*2 DPLTYP 
COMMON/DUMPLG/DPLNO 

INTEGER*2 DPLNO 
COMMON/DOMPLG/DPLSTR 

INTEGER*^ DPLSTR 
COMMON/DDMPLG/DPLEND 

INTEGER*!! DPLEND 
COMMON/DOMPLG/DPLDAT 

INTEGER*^ DPLDAT 
COMMON/DUMPLG/DPLDD 

L0GICAL*1 DPLDD(8) 
COMMON/DUKPLG/DPLIST 

INTEGER+U DPLIST 
C END OF COMMON NAMED 'DUMPLG* 
C 

DPLMAC 

A halfword binary value of 52 identifying the requested service to 
the interface routine- 

DPLRC 

A halfword binary field containing a binary number return code from 
the DUMPLOG service routine. See DUMPLOG macro write-up for possible 
values. 

DPLTYP 

A halfword flags field indicating the requested options to the GETLOG 
service routine. Bits are numbered 0 to 7. 

Bits 0, ^, 

2, 4 and 7 — Reserved 

Bit 3 — This flag specifies whether the dumped copies are 

to be written at the beginning of the dump data set 
(Bit 3 is on) or added to the existing dumped copies 
(Bit 3 is off) . If the disposition parameter 
specified on the DD card statement for this data 
set is either OLD or SHR and the data set is empty, 
then the first DUMPLOG request must specify 'NEW' 
(Bit 3 is on). Specifying "NEW* (Bit 3 is on) on 
subsequent DUMPLOG requests will position a direct 
access data set to record one and will cause a tape 
data set to force EOV bofore the log copies are 
written. 

Bit 5 — If on, specifies a list of array names or numbers 

is pointed to by DPLIST. 

Bit 6 — If on, specifies array nufflber(s) is to be processed. 

If off, array name(s) is given for processing. 
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DPLNO 

A halfword number i#hich is the number of a numbered array to be dumped. 
Valid only if Bit 5 is off and Bit 6 of DPLTYP is on. 

DPLSTR 

A fulltford which specifies the address of a 6-byte time and day field. 
The first four bytes will contain a time in 10-millisecond The last 
two bytes will contain a binary value from 1 to 266 representing the 
date of the year. The logged copies of the array will be searched 
until a copy is found with a log time equal to or greater than the 
start time specified. If this parameter is zero, dumping commences 
with the oldest logged copy of the array. 

DPLEND 

A fullword which specifies the address of a 6-byte time and day field 
formatted as in DPLSTR. The logged copies of the array will be dumped 
until the most recently logged copy has been dumped or until a copy 
is dumped whose log time is equal to or greater than the specified 
stop time. If this parameter is zero, dumping will terminate when 
the most recently logged copy of the array has been dumped. 

Note: DUMPLOG will insert a byte of X»FF« into the first byte of the 
logging header of the last copy of each array dumped to the 
sequential data set to indicate the end of the dump of each 
array to the user delog routine. 

DPLDAT 

A fullword which specifies the address of a 256-byte user data area 
to be contained in the dump header for each array on the sequential 
damp data set. 

DPLDD 

Two U-byte logical words containing the name of the data definition 
(DD) statement which describes a sequential data set to receive the 
dumped copies of the array (s) from the log data set. A name must be 
specified. 

The output will consist of spanned variable length records. The 
blocksize of the data set defined by DPLDD must be at least 264 bytes 
but no more than 32,760 bytes. The blocksize should be large enough 
to contain one array copy, its log header, the user dump header, if 
any, and the variable length descriptor words (8 bytes) for maximum 
ef f iency . 

DPLIST 

A fullword containing the address of one of the following based on 
Bits 5 and 6 DPLTYP: 

a- If Bits 5 and 6 are off, then DPLIST contains the address of an 
8-character loggable array name to be dumped. 

b. If Bit 5 is on and Bit 6 is off, then DPLIST contains the address 
of a list of loggable array names to be dumped. 



APPLICATION SERVICES 2-149 



Each name is eight characters long with a X'FF* after the last valid 
name as an end of list indicator. 



NAME LIST 



0 ARRAY NAME 



8 ARRAY NAME 



16 FF 



c. If Bits 5 and 6 are on, then DPLIST contains the address of a list 
of half word loggable array numbers. A X* FF' follows the last valid 
number as an end of list indicator. 



NUMBER LIST 



0 NUMBER 



2 NUMBER 



4 FF 



The DUMPLOG service may be invoked by CALLing DPPPIF with a properly 
completed parameter list. 

The following example will dump log array B at the beginning of the 
data set. All log copies of array B will be dumped starting with the 
oldest copy available. 

C FORTRAN DUMPLOG EXAMPLE 
BLOCK DATA 

COMMON /DUMPLG/ DPLMAC, DPLRC, DP LT YP , DPLNO, D PLST DPLEND, 
1DPLDAT,DPLDD(2) , DPLIST 

INTEGER DPL MAC* 2/52/, DPLRC* 2/0/, DPLTYP* 2/0/, DPLN0*2, 
1DPLSTR,DPLEND,DPLDAT, DPLIST 

LOGICAL DPLDD*4/' DUMP' , 'LOG '/ 

END 

(The above common areas should be repeated in the main program without 
data initialization. The following statements are in MAIN only.) 

LOGICAL A*4{2)/'B ',' ' /, DISP*1/Z 10/ 



CALL ORBIT(DPLTYP,DISP) 
DPLIST = IADDR(A(1) ) 
CALL DPPPIF (DPLMAC) 
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DUPLICATE DATA SET SUPPORT 



The operation of the Special Real Time Operating System and associatea 
subsystems is dependent upon several direct access data sets. Some of 
these, such as data base definitions, are only read in realtime 
execution, while others, such as history logs, are read and written. 
The Special Real Time Operating System provides the capability to use 
two identical copies of certain data sets to improve the total system 
availability. While this service is provided primarily for data sets 
which are used by the system, a limited capability is provided to the 
system user to utilize the duplicate data set support. 

The principal purpose of the duplicate data set facility is to provide 
a backup copy of the data should the primary copy experience a failure. 
In maintaining this duplicate data set, the primary and backup are 
updated simultaneously during realtime processing. In case of failure 
of one copy, the system takes that copy out of service and uses the 
other copy. Appropriate messages are output to make the operator aware 
of the troiible. 



Duplicate data set support (DDS) is a SYSGENable option which is 
selected by coding the DOPDISK macro at Special Real Time Operating 
System SYSGEN time. With DDS SYSGENed, a user can declare via JCL the 
data sets that are duplicates. The user programs include special I/O 
macro codes to use the DDS services. Hoaever, this does not prevent 
these programs from functioning when DDS is not supported, because the 
special macros default to their standard 0S/VS1 counterparts for data 
sets not supported by DDS, 



DDS services are in three logical areas: 



1, Initialization 



2. Pseudo-svc routines 



3, I/O CALL routines 



Initialization analyzes the DDS input stream to determine which data 
sets are being declared as duplicate, A control table is established 
for properly declared duplicate data sets, and its address is placed 
in the Special Real Time Operating System SCYT, 

The DDS pseudo-svc routines are given control when the user requests 
an I/O function which is normally an SVC under standard OS access 
methods. Thus, the OPEN, CLOSE, BLDL, FIND, and STOW macro functions 
require corresponding DDS macros (OS macros preceded by DDS) which 
expand not to an SVC, but to a branch to the respective DDS routine. 
If the data set has been declared a duplicate, these routines will 
issue the SVC for both data sets; if not, these routines will issue 
the SVC only once. The DCBOFLGS and SVC return codes are provided to 
the user in either case. 



DDS I/O call routines will be entered for all I/O requests (READ, WRITE 
NOTE, POINT, and CHECK) to a data set that was opened with the DDS OPEN 
macro and was declared a duplicate. These routines will treat the 
request in the following manner: all requests to alter the data set 
are issued to both data sets, and all requests to read data are issued 
only to the primary data set. In the update mode, the read request is 
issued twice. In case of an incorrectable I/O failure, the failing 
data set is closed, and processing continues with the remaining data 
set- For double I/O failures, the user's SYNAD is given control- To 
prevent double I/O failures, the data sets should be on devices that 
are on different I/O channels. 



APPLICATION SERVICES 2-1 



The user declares which data sets are duplicates via JCL, by including 
the DD card DDSCTLIN. Each duplicate data set should be described by 
a separate 'DDSNAMES' card in the DDSCTIIN stream. The format of the 
DDSNAMES card is as follows: 

[ DDS-DDNAME ] DDSNAMES (D DN All El ,DDN AME2=0UT) 

DDS-DDNAME 

Is optional and must begin in column 1. It should be the DDNAME that 
will be referenced in all I/O macros for this duplicate data set. If 
left blank, its value will default to that supplied in the DDNAME1 
field. 

DDSNAMES 

Is the required op code and should be preceded by at least 1 blank, 
DDNAME1 

Is the DDNAME of the DD card for the primary data set of the duplicate 
pair. This field is required- 

DDNAME2 

Is the DDNAME of the DD card for the backup data set of the duplicate 
pair. This field is required and the backup can be initialized out 
of service. 

Certain DDS functions can be requested dynamically during realtime 
operation. These functions allow the user, through the input message 
processor, to: 

® Create a backup 

• Take a backup out of service 

• Switch the primary and backup 

• Replace the primary 

• Compare primary and backup 

• Give the status of the duplicate data sets. 

The format of the replies required to invoke these routines is 
documented in the section entitled "DDSCNTEL Command. The input message 
command is DDSCNTRL, 

The user can have his current primary data set copied to his backup to 
bring the backup to the same level as the primary. This operation 
requires that the backup data set be out of service for the copy 
operation. The user also may use the DDSCNTRL reply to take the backup 
out of service. 

The DDSCNTRL reply may be used to cause the backup to become the primary 
and have the primary switched to an out of service backup- But backup 
must be in service at the time of the switch request. 

A primary data set may be replaced by another data set specified by 
DDNAME on the DDSCNTRL command provided that no DDSDCB opened for the 
duplicate data set exists at the time of the request. This would cause 
the new DDNAME to become the primary copy and the old primary to become 
the in-service backup copy- 

The user may wish to verify that his primary and backup copies of a 
DDS are, in fact, the same. He may do this with the COMPARE operand 
of the DDSCNTRL command. To invoke this operation^ he must be sure 
that a COMPRINT and DDSCMPIN DD card was supplied. When invoked, the 
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OS/VSI utility lEBCOHPH is used to do the compare. To use this operand, 
LRECL lust have been specified on the DDS DD cards for partitioned data 
sets. 

See Section 3, entitled "DDS INITIALIZiTION" for a description of DD 
card usage. 

The status of the prinary and backup DD naaes nay be determined (in or 
out of service, which is priaary, vhich is backup) by invoking DDSCNTRL 
vitk the STATUS operand. 

The following is a list of restrictions and guidelines for using the 
DDS services. 

1. All duplicate data sets must begin on a cylinder boundary and 
can have only one extent. 

2. The user should be certain that any two data sets being declared 
as duplicates are, in fact, identical in their content. 

3. Two tasks can xreference the same DDSDCB provided it is treated 
as a serially reusable resource. In update node the user oust 
treat each READ-CHECK and iRITB-CRECK operation as a single 
function. 

4. Only Disk resident data sets can be declared duplicates. 

5. Only one DDS DCB per DDS can be opened at a time. 

6. Vo copy and control functions can be used if the DDSDCB is opened 
for update (BP AH or BSAH). 

7. DDS services are available only to the Special Real Tine 
Operating System tasks. 

8. Only 20 duplicate data set pairs are supported. 

In the folloving example of typical use of DDS, the user wishes to 
create a duplicate BP AH data set and update an existing BSAH duplicate 
data set. The job step JCL would include these cards: 

//BPAH1 DD DSM=BPl,DISP=(NEi,PASS) ,SPACE=(CYL, ) ,ONIT=DISK 

//BPAB2 DD DSH=BP2,DISP= (NEW,PASS) ,SPACE=(CTL, (1,, 1) ) ,UNIT=DISK 
//BSAH1 DD DSH=BSH1, DISP=(OLD,PASS) 
//BSAH2 DD DSH=BSH2,DISP= (OLD, PASS) 
//DDSCTLIH DD ♦ 

DDSNAHES ( BP AH 1 , BPAH2) 

DDSMAHES ( BS Afl 1, BS AH2) 

/* 

The OPEN and DDSDCB macros would be coded as follows: 

DDSOPEH (DDSBP1, (OUTPUT) ) 
DDSOPEM (DDSBSH1 , (UPDAT) ) 

DDSBP1 DDSDCB DDNAHE-BPAH1,. 
DDS6SR1 DDSDCB DDNAH E=BSA Hi , 

The READ, HfilTE, and CHECK macros would be coded exactly as if they 
were standard OS. 
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The STOW and CLOSE macros vould be coded as follovs: 



DDSSTOH DDSBP1, LISTER 

LIST DC CL8« HEHBEP1 • ,XLU« 0» 

DDSCLOSE (DDS^PI) 

DDSCLOSE (DDSTsnl) 

DOS FAILOVER/RESTAHT CONSIDERATIONS 



The status of each declared DOS will be kept on a disk resident data 
set with DDN»ME, DDSTATOS. All chanqes (via COPT and CONTROL) will be 
recorded on this data set. In the case of faiiover or restart, the 
status of each DDS will be taken froa this data set. 



If the user wishes to use an ezistina DDSTATUS for his declarations at 
initialization time, he must include in his DDSCTLIN input stream a 
REFRESH card as the first card (REFRESH can beqin in any colunn except 
column 1)-; Ail the remaining cards (if any) will be ignored, and the 
declarations currently on the DDSTATOS data set will be used. 

When initialising a backup computer, the first card in the DDSCTLIN 
input stream must be READONLY which may start in any column except 
coluan 1. This will inhibit all data transfer to disk by DDS until 
failover occurs and this Machine becoaes pciaary. READONLY iaplies 
refresh; so the current declarations on DDSTATUS will be used. 



When DDS is entered during failorer/restar t, it expects all DDSDCB to 
be closed. Any task which has a DDSDCB opened at that tiae will be 
ABENDed with code 81 decimal (51 hex). Normal task clean up will then 
close the DDSDCB and free the associated storage gotten by DDS. 



FAILOVER/RFSTART FEATORE 



The f aiiover/restart feature of the Special Real Time Operating System 
is SYSGEMable and optionally provides the continuous monitor and probe 
function and the coaputer status panel. 

Failover/restart operates by copying the contents of virtual storage, 
the 0S/VS1 iob queue, and the SWADS for the one or two partitions that 
encoapass the realtiae job, into a disk data set. If two-partition 
operation is being used, both SYSIHIT streams must contain RESTART 
WRITE statements. The writing of the failover/restart data set is 
delayed until both partitions execute this statement. After this data 
set is written, a "bootstrap" record is written at the front of the 
data set, and the IPL1 and IPL2 records on the volume containing this 
data set are adjusted to allow then to read in the bootstrap prograa. 
Thus, the volume containing the failover/restart data set becomes an 
IPLable volune. IPLing this voluae is the method of accoaplishing the 
restart. If this occurs on a different CPO, the operation is known as 
a failover. 



The effect of IPLing this voluae is to return the System/370 to the 
identical state it was when the RESTART WRITE card was encountered in 
the STSINIT Special Real Time Operating System initialization stream- 
This is illustrated in Figure 2-27. The failover/restart bootstrap 
restores virtual storage, the job queue data set, and one or two SWADS 
data sets to the identical state they were when the restart was written. 
No savinq or restorinq of the SYS1.SYSP00L data sets occurs. Ose of a 
scheduler work area (SWA) in place of SWADS by the MASTER or SLAVE 
partition will cause the SWADS not to be saved. The equivalent 
information is available within the partition. 
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Figure 2-27. Restart Process 

Realtime jobs which use the fai lover/ re start feature Bust observe the 
following restrictions: 

1. The failover/restart data set and its copies must reside on a 

direct access volume. The volume may be on any device supported 
by 0S/VS1. It may not be the volume containing the SYS1-NUCLE0S 
data set (OS IPL volume) . No aore than one failover/restart 
data set may be allocated on a volume- The failover/restart 
data must not be an OS temporary data set; it must reside 
entirely upon one volume and can contain only one extent. (Only 
the first extent will be used.) 



2. The failover/restart data set should be allocated on a cylinder 
boundary- SYS1- SYSJOBQE and the SWADS data sets must end on a 
cylinder boundary. 

3. The SWADS data sets cannot be temporary data sets unless SBA is 
used in place of SWADS. 

4. No data set used by the realtime job should be a temporary data 
set nor should the realtime job be dependent on SYSIN data sets 
after the RESTART WfelTE card is executed. Because the job is 
never ending, it should not use DD cards containing the SYSOOT 
parameter. If such SYSIN/SYSOOT data sets are used, contents 
may be lost. This does not apply to the SYSINIT input stream 
as it is read in its entirety prior to executing any of it. 

5. No tape positioning is done by failover/restart. 

6. At the time of restart read, all necessary direct access volumes 
must be mounted and ready. Data sets that are to be referenced 
and were allocated prior to restart write must exist on the same 
volume as they did prior to restart write. If DCBs were opened 
for any direct access data sets prior to restart write, these 
data sets must occupy exactly the same physical disk location 
they did prior to restart write* The device address upon which 
a particular volume resides may differ, however. A necessary 
volume is one that contains a system data set or that is 
allocated to the realtime job- 

7. At the time of restart read, multiple volumes with the same 
volume serial number must not be accessibiej There-NiP routine 
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will attempt to read the volume serial number from all direct 
access devices which were SYSGENed into the 0S/VS1 system. 

8. At the time of restart write, the user should take steps to 
ensure that no jobs are active in the CPU other than the realtime 
job and its SLAVE partition job, if any. If this restriction 

is ignored when the f ailov er/restart data set is IPLed, these 
jobs will resume at the point where they were written without 
the benefit of a restored SWADS and possibly with data extent 
blocks (DEBs) containing invalid disk addresses. Resumption 
could occur in the middle of a DADSM function, thereby 
compromising VTOC and data set integrity. 

9. Restrictions 3 through 8 do not apply if the f ailo ver/restart 
is to be written, but never read. Restrictions 1 and 2 apply 
in any case. 

10. The Special Real Time operating System initialization routine 
invokes restart when the RESTART WRITE card is encountered in 
the execution pass of the SYSINIT input stream. This is executed 
by issuing the HTFAILDS macro (no operands). A user program 

can also issue this macro. Use of this feature repetively (to 
take checkpoints) is not recommended for all the reasons listed 
above. In addition, since each execution of WTFAILDS would 
cause the existing copies of the fai lover/ restart data set to 
be overlayed, a failover in the middle of the restart write 
could result in no usable failover/restart data set, old or new. 
Failover/restart is a method of getting a fast IPL; it is not 
a substitute for checkpoint restart. 

11. If a failover/restart data set is to be written on one CPU and 
potentially read by any CPU other than the creating one, the 
following restrictions should be observed: 

a. The CPUs should have identical configuration or the 0S/VS1 
system involved should be a superset of all the CPUs. 

b. The CPUs should all be of the same model at the same 
EC/feature level to ensure that RMS will operate correctly. 

c. If the CPUs are of different real storage sizes, the 
failover/restart data set must be written by the one with 
the smallest real storage size. When IPLed on the larger 
CPU, this CPU's extra real storage will not be used. 

12. A copy of a failover/restart data set can be made only by using 
lEHDASDR (an OS/VSl utility) or DOMIRCPY (a Special Real Time 
Operating System utility to copy failover/restart data set) . 
lEHDASDR can be used only in the sense of making a tape backup 
for later restore. 

13. The WTFAILDS macro should not be used by an application program 
if the Time Drift Correction feature is used. This does not 
preclude the use of the RESTART WRITE statement in the DPPINIT 
input stream. 

When failover/restart write is invoked, it copies all of virtual 
storage, SYSI .SYSJOBQE, and the SWADS data set(s) to the data set 
allocated by the DPPFAIL DD card. Copying of virtual storage consists 
of copying all real storage and those entries on the paging data set 
which are active. After the writes to DPPFAIL are completed, the 
desired backup copies of the entire failover/restart are made by copying 
from DPPFAIL to DPPFAILx, where x is a unique character (the anethod of 
copying the Failover data set is described later in this section) . 
Each DPPFAILx must reside on a unique volume which is of the same device 
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type as DPPFAIL. This operation has no connection with duplicate data 
set support and is independent of it. 

Failover/rest art data set write will not write the f ailover/resta rt 
data set if another realtime job (MASTER JOB) reached the Special Real 
Time Operating System initialization prior to the job issuing the 
WTFAILDS (or RESTART WRITE card)„ If this occurs, WTFAILDS will be 
treated as non-operative; although the pre-restart flag in SYSINIT 
PATCHes will be cleared* When the job having 'ownership' of 
f ailover/restart eligibility terminates, the next MASTER realtime job 
that starts will acquire it- In addition, if the byte at displacement 
X'OD' past the CSECT/ENTRY name DPPICINF in the OS/VSI nucleus is 
nonzero, no job will acquire restart write eligibility. This byte is 
assembled as non-zero, but may be altered by using HMASPZAP, an OS/VSI 
service aid. 

(The name DPPICINF will be a CSECT name in the pageable nucleus in the 
Special Real Time Operating System without external interrupt handling; 
that is, without the TIMEEXT option or the CLOCKCP option on the VS 
SYSGEN macro and without the FAILEXT option on the FAILRST macro. In 
systems with external interrupt handling, it will be an ENTRY name in 
the CSECT IEAXYZ5-) 

The return codes issued by WTFAILDS are listed below^ 



GR15 


MEANING 


Message Written to Routine 
Code 5 


0 


DPPFAIL 

data set written successfully 
or failover/restart write 
suppressed by other R/T job. 


DPP090, DPP093 


4 


same return code as 0 except 
restart data set was just read. 




DPP091 


8 


Invalid or missing DPPFAIL 
DD card. 


DPP092 


12 
10 


I/O error writing DPPFAIL 
or end of extent 


DPP080-DPP087 



When IPLing a failover/restart data set, several WAIT states can occur. 
They are listed below: 

Code Description 

X*18' CPU too small for failover/restart data set or other 

immediate program check in bootstrap. 

X'19» Program check in bootstrap while copying data sets 

or I/O error. 

X'E2' Machine check in restart bootstrap. 

X'03' One or more necessary disks missing. 

Program check loop Failover/restart data set has been scratched. 

Hangs in LOAD Failover/restart data set has been scratched or I/O 

error. 



The load module DOMIRCPY is used internally by failover/restart write 
to copy DPPFAIL to DPPFAILx DD cards. It can also be invoked as a 
PATCHed task to perform the same operation in any realtime job, which 
is shown in the example below. 
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Return codes from DOniRCPY 



GR15 


MEANING 


Message to Routing 
Code 5 


0 


Copy Successful 


None 


8 


One or irn)re invalid 
DPPFAIL oi DPPFAILx DD 
cards. No copy done. 


DPP089 


12 


I/O error during COPY. 
COPY terminated. 


DPP088 



//X 

// 

//STEPLIB 
//SYSPRINT 
//DPPFAIL 
//DPPFAIL2 
//SYSINIT 
COPY PATCH 
WAIT 
ABEND 

// 



JOB 

DD 
DD 
DD 
DD 
DD 



1, 1,MSGLEVEL=1 
EXEC PGM=DPPINIT 

SYSOUT=A 

DSN=FAILRST. DS ,DISP=SHR 
DSN=FAILRST2. DS, DISP=OLD 
* 



OLD F/RD/S 
NEW F/RD/S 



EP=DOMIRCPY 

COPY 

0 



Example 1 



CoStiGMOJJS Monito r 

The continuous monitor feature of the Special Real Time Operating System 
is available in all systems having the f ailover/restart feature. Its 
selection is made by coding the CONTMON parameter on the FAILRST SYSGEN 
macro. 

The continuous monitor is started by PATCHing a task with EP=DOKIRCMN. 
This can be done by a user program, by a PATCH card in the SYSINIT 
input stream, or by the CMON parameter on the RESTART card, DOHIRCMN 
is a never ending program. DOHIRCMN should be invoked after the 
failover data set is written, if a f ailover/restart data set is being 
written. 

''he continuous monitor tests certain locations within the Special Real 
.'ime Operating System virtual storage data base on a periodic basis, 
"'he period is determined by the CONTINT parameter on the FAILRST macro. 

If the continuous monitor determines that the test locations have not 
been modified for a certain period of time (indicating that some cyclic 
function has failed), it recommends that failover occur. The action 
taken depends upon the mode of operation of the continuous monitor, 
simplex or duplex. A system without a probe function generated (PROBE 
parameter in FAILRST macro) always operates in the simplex mode. In 
a system with the probe function, the continuous monitor operates in 
duplex mode unless one or both of the following conditions are met: 

• The realtime job under which the continuous monitor is operating 
is not authorized to write a failover/restart data set (see 
Failover/Restart section) . 

• A probe function is running under any job on this CPU. 

If either of these conditions is met, the continuous monitor will 
operate only in simplex mode. In the simplex mode, when the continuous 
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monitor recommends faiiover, it issues message DPP098 and places the 
task under i#hich it is executing in a permanent BAIT. In the duplex 
■ode, the continuous sonitor s>ends a siqnal Tia the direct control 
feature to the backup CPD that the continuous monitor is recommending 
failoirer. This siqnal is received by the probe function in the backup 
CPU. The backup CPU then initiates the failover. 

The test locations exaained by the continuous sonitor are either 
determined implicitly by the options generated into the systea, or 
additional customer test locations can be stated explicitly in the 
CONTROL parameter of the PAILRST SYSGEN aacro. Each location to be 
tested is a 2-byte named, virtual storage resident data base item. 
This 2-bvte itea should be defined in a n ITBH aacro as initially 
zero. The first byte of the item is the period in seconds at which 
the second byte will be updated. The second byte should be changed 
from 1 to 2, 3, up to 250, back to 1 again at the rate specified 

in the first byte. If the value fails to chanqe for a tiae interval 
equal to twice the first byte, the continuous aonitor will recoaaend 
failover. If the second byte is zero, it indicates that the data base 
itea will no lonaer be increaented at the rate specified and should 
not be checked again until it is once again nonzero. A value of 255 
(hex PF) in the second byte indicates that the coaponent is recoaaending 
failover. If this occurs, the continuous monitor will recommend 
failover. Values of 251 through 25U are reserved for expansion. 

Noraally, the continuous aonitor sends periodic signals to the probe 
function, but the converse does not occur. To have the continuous 
monitor report if the probe function is no longer checking it, the 
cnCKPPB parameter should be set to YES on the PAILRST SYSGEN aacro. 

Pyo be Punct ion 

The probe function is a SYSGENable option of the Special Real Tiae 
Operating System f ailover/restart feature. It operates in the backup 
CPU and tests the online CPU (the continuous aonitor) via the direct 
control data bus. If the U-bit value represented on the static siqnal 
lines fails to chanqe for a tiae interval of twice the saaple period 
(CONTINT parameter) , the probe function recoaaends that the backup CPU 
become the prim*^ CPU. The location of the 4-bit quantity on the static 
sianal lines is determined by the PROBIT parameter of the FAILRST macro. 
These four lines must be connected between the two CPUs so that a siqnal 
placed on t h*^ lines by iJRD in one CPU can be read by ROD in the other 
CPU and vice versa. & value of 15 (hex P) on the lines indicates that 
the continuous monitor is recommending failover to the probe function 
because the continuous monitor found a value of 255 in one of the data 
base items examined, or that the continuous monitor is recommending 
failover to the probe function because one of the test locations has 
failed to chanae at its specified rate. Thus the probe function will 
recommend failover when it qets a Continuous Monitor Recommended 
Failover siqnal or if the continuous monitor fails to change the bits 
on the static sianal lines at the specified rate. (This could occur 
if the prime CPU went down.) In a system without the failover confirmed 
external interrupt (?»ILEXT parameter on the PAILRST macro), Failover 
Recommended is the same as Failover Confirmed (see Figure 2-28). 
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Figare 2-28. Probe Punction Failure/Restart Feature 

The probe function can be started in a realtine or non-realtime job. 
It will not start if another probe function is already operating on 
this CPO, or if a continuous monitor function operating in duplex mode 
is running. The probe can be started by the RESTART card in the Special 
Real Time Operating System SYSINIT stream or by a user program. It 
should be started on the backup CPU after the continuous monitor has 
been started on the primary CPO. If the probe is started first, it 
will immediately recommend failover. 



The action taken by the probe when it enters the Failover Confirmed 
state is determined by its entry point. If the probe was entered at 
EP=DOMIRPRB, it will simulate a hardware IPL to the direct access device 
pointed to by the DPPPilL DD card. This device should contain a 
successfully written f ailover/restart data set. If the probe was 
entered at EP=DOHIRPaT, it will return to its caller with a code of u 
in register 15. Coding the PROBE parameter in the RESTART card causes 
the DOHIRPWT entry to be used. 

The DOniRPRB entry point is intended for use in a duplex CPO environaent 
where a system outage of 15 to 60 seconds can be tolerated. Opon 
reaching the Failover Confirmed state, DOMIRPRB will simulate a hardware 
IPL to the f ailover/restart data set. The realtime system will resuae 
at a point after the execution of the RESTART URITE card in the SYSINIT 
stream or the issuance of a WTFAILOS macro by an application program. 
The jobs, SYSIN and SYSOOT, and operating system running on the backup 
CPO prior to the simulated IPL will be lost. 

The DOHIRPWT entry point is intended for use in duplex environments 
where a faster failover is needed. Osing this scheme, the PROBE 
parameter is coded on the RESTART card. This causes the PROBE to be 
invoked after RESTART WRITE, if any. This causes a delay in the Special 
Peal Time Operating System initialization until the probe function 
returns. Thus initialization stops until the probe enters the Failover 
Confirmed state. While the realtime job is executing only the probe, 
much of the remainder of it will be paged out by OS/VSI. Batch jobs 
can then be run. If the offline CPO later becomes the online CPO, 
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these batch jobs can be cancelled if they are interfering with the 
realtime job. The following example depicts a sample SYSINIT stream 
for this type of operation. 



EXEC 



PGM=DPPI NIT 



//SYSINIT 

PATCH 
PATCH 
RESTART 
PATCH 
PATCH 

/* 



DD * 
EP=ONE,TASK=X 
EP=TWO,TASK=Y 
WRITE, PROBE, CHON 
EP=ONEONE, TASK=X 
EP=TWOTWO, TASK=Y 



INIT TASKS 

(IMPLIED WIAT ON ABOVE TWO) 



Remote System Reset 

The Special Real Time Operatii g System supports the remote system reset 
RPQ (Z06741) in systems with the continuous monitor and probe function- 
This feature allows one CPO to force another CPU to execute a system 
reset. The probe function resets the online CPO which has just failed 
when it enters the Failover Confirmed state. Since during a failure 
the online QPU may have degraded to a disabled loop and has I/O devices 
reserved, this feature increases system availability by giving the 
backup CPU the ability to force a system reset in the online CPO. The 
RESET parameter in the FAILRST macro is used to include this feature 
in the probe function. The operand of the RESET parameter is a direct 
control signal-out line number (0-7) for the reset feature. Figure 
2-29 depicts a two-CPU configuration with remote system reset. 



Shared 
I/O 



Direct Control 
Static Data Lines 
(4 Bits Used) 



CPU A 




CPU B 


(SYSRESET) Signal-out Line 


Signal-out Line (SYSRESET) 





Figure 2-29. Remote System Reset Feature 



Eemote 29ia Switch 

The Special Real Time Operating system also supports the automatic 2914 
Remote Equipment Switch RPQs (880882 and 880920) in a system with the 
continuous monitor and probe functions. This feature allows devices 
which are connected to two CPOs through a 291U switch to be 
automatically switched from the prime CPU to the backup CPO. When the 
probe function enters the Failover Confirmed state, it will cause the 
2914 to switch the shared equipment to the backup CPU. The EQUIPSH 
parameter on the FAILRST macro specifies which direct control signal-out 
line (0-7) is to be used to cause the 2914 to switch shared equipment 
to the CPU issuing the direct control instruction. The EQUIPDY 
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parameter specifies in milliseconds how long the probe function should 
delay after issuing the 2914 switch command until it returns (DOHIHPWT) 
or IPLs the f ailover/rest art data set (DOMIRPRB) . Figure 2-30 depicts 
a two-CPU configuration with 291U remote switching. The remote system 
reset, 291U Remote Switch, and computer status panel features are all 
independent of each other. 



Shared I/O 
(Two Channel 
Switch Type) 



CPU A 



Direct Control 
Static Data Lines 
(4 Bits Used) 



" Switch to Me 
Signal-out Lines 




" Switch to Me " 
Signal-out Lines 




Figure 2-30. System With Automatic 2914 Switch 



Computer Status Panel 



The Special Real Time Operating System offers software for the computer 
status panel (see Figure 2-31) as an option for systems with the 
continuous monitor and probe features. In addition a smaller model 
can be supported for systems with only the continuous monitor feature. 
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Figure 2-31. Coiputer Status Panel Indicators and Switches 

The coaputer status panel consists of six indicator lights and two or 
three backlighted pushbuttons. The Computer k Prime/Computer B Prime 
lights are Butually exclusive; the one that is lit indicates which 
system is currently the online (priae) CPU. This light is illuminated 
by a pulse from a direct control signal-out line on the system that is 
the online system. It retaains lit until a pulse is received on the 
same signal-out line on the other CPU, in which case the other PRIME 
light is lit. The Computer A Feady/Computer B Ready lights are 
illuminated by a signal on the direct control signal-out lines. They 
remain lit for approximately two seconds at which point they extinguish 
(time-out) unless they are re-illuminated prior to that tine by another 
pulse on the same signal-out line. This light indicates that the CPO 
is successfully executing the online system or is capable of becoming 
the online system if it is the backup computer (probe function is 
running). For systems without a probe function, only these two 
indicators (four bulbs) are supported. 

The Computer Failover Request light is illuminated by a bit on a direct 
control static data line. As long as the bit on the line is one, the 
Light remains illuminated. Illumination is by the probe function when 
it enters a Failover Recommended state. The Select light backlighted 
pushbutton is lit by the probe function when it enters the Failover 
Confirmed state. This indication means that failover has begun. The 
Select and Failover Request lights are extinguished and the prime light 
is lit when the continuous monitor function starts to execute on the 
new failover- to-pri me CPU. 
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In systeas without the Paiiover Confiraed external interrupt (F?.ILEXT 
parameter on the FAILRST macro), the Pailover Request and Select liqhts 
are illuminated simultaneously as the Faiiover Recommended and Failover 
Confiraed states are the same. In systems with the Failover Confiraed 
external interrupt, the Failover Request light will be illuminated when 
the probe function enters the Failover Recoamended state. If the Auto 
Failover ?.ctive switch is on (is backlighted), an external signal 
interrupt occurs in the CPO lighting the Failover Request light. (Which 
external signal used (2-7) is indicated in the FAILEXT operand of the 
FAILRST macro.) This external interrupt causes the probe function to 
eater the Pailover Confiraed state. If the Auto Failover Active switch 
is off, the SELECT bac)clight pushbutton must be pressed to cause the 
probe to enter the FailOTer Confiraed state. (The SELECT button causes 
the same external interrupt.) 

If the continuous monitor begins to change the bit configuration on 
the four direct control static data lines, during the tiae the probe 
function is in the Pailover Recommended state, the probe function 
extinguishes the Failover Bequest light and resuaes noraal operation. 

In systeas with the Failover Confiraed external interrupt feature, the 
SELECT pushbutton may be pressed at any time to force a failover. The 
SELECT pushbutton on the online coaputer aay be pressed to force a 
restart. Vhen the continuous monitor forces an IPL of the 
Pailover/Restart data set, it places a special (14 hex E) bit 
configuration on the direct control static data lines to indicate that 
the ppobe function should delay one ainnte before continuing its 
checicing of the online CPU. 

The IPL that is forced by the continuous monitor is achiered by XCTLing 
to DOHIRIPL. This module exists in all systems vith a probe function 
and aay also be called by a user prograa (via CALL, LIHK, XCTL, ATTACH, 
or PATCH) to force an IPL of the fail over/rest art data set. 

The LTS parameter on the FAILRST macro is used to indicate which 
signal-out and static data lines are used to support the coaputer status 
panel. Figure 2-32 depicts a two-CPO configuration with a computer 
status panel. 

The computer status panel is not an RPQ and aust be fabricated by the 
customer. 



2-164 



Description and Operation Manual 



Shared I/O 



4 Bits of 
Direct Control 
Static Signal Lines 




Figure 2-32. Computer Status Panel Connections (Functional) 
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ADDITIONAL SPECIAL FEAL TIME OPERATING SYSTEM SERVICES 

There are additional Special Real Time Operating System services that 
do not fall into the areas of task management or time management, etc. 
These additional services are: 

CHAIN 

GETWA/FREEWA 
LOCK/DEFLOCK 
PAGE FIX 



CHAIN 

CHAIN allows a programmer to modify a control block chain without the 
need of ENQ/DEQ to protect against another program modifying the chain 
at the same time. CHAIN operates as a Type I SVC. CHAIN can be used 
to add (ADD) a block (BLOCK=) to a specified chain (OEG=) or delete 
(REMOVE) a block from a chain. The block to be added (BLOCK=) may be 
placed at the start of the chain (POS=FIRST) , the end of the chain 
(POS=LAST) , or to put the block into the chain in a collating seguence 
(POS=disp) . To place the block in collating seguence, the POS=disp 
specifies the displacement into the block to a word which is to be used 
to determine the block's relative position on the chain. This is sh3wn 
below: 

CHAIN ADD,OPG=START,POS= 12,BL0CK=X 



START 



00000052 



00000026 



1 WORD- 



00000042 




0000007C 



In this example, block X will be added to the chain and will be inserted 
between blocks S and P. 

If the blocks on the chain are not chained together by pointers in the 
first word of each block, the chaining field can be specified by INDEX= 
and supply the displacement into the blocks which are to be used for 
chaining pointers. 

CHAIN will also post an ECB upon completion if the (ECB=) user reguests 
this action. 

All addresses are validity checked and must be within the partition 
(or either partition if two partition operation) . 



3ETHA/FREEWA 

The GETWA/FREEWA function provides the facility for obtaining short-term 
work areas without adversely increasing paging rates and without 
incurring all the overhead of a GETMAIN. The amount and sizes of GETWA 
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areas are determined by the Special Real Time Operating System SYSGEM 
(VS Macro, GETWAS=) and may be changed at the Special Real Time 
Operating System initialization time by a GETHA card. The number of 
unique GETHA sizes is limited to 32. The maximum size of a GETWA area 
is limited to 30710 bytes. All sizes greater than 2048 bytes must be 
defined as a multiple of 2K. All must be defined as a multiple of 8 
bytes. 

Note: The Special Real Time Operating System requires a minimum GETWA 
size of 102U bytes. 

GETWA storage is requested via the GETIfA macro and may be explicitly 
freed by FREEWA. The requestor may have the Special Real Time Operating 
System free the storage for him and thereby relieve himself of the 
necessity of keeping track of his GETHA storage. To have the Special 
Real Time Operating System free the gotten storage, he must use the 
TYPE= operand on his GETWA request. TYPE=AP requests the Special Real 
Time Operating System to release the GETWA storage when this PATCH 
completes. TYPE=AT frees TYPE=AT frees the storage when the task 
terminates (a DPATCH is issued) . TyPE=PC is specified when the user 
wishes to free the storage explicitly with the FREEWA macro. Storage 
obtained with TYPE=PC will be lost to the system if the requesting task 
terminates and does not execute the FREEWA. Programs which are ATTACHed 
rather than PATCHed are defaulted to TYPE=PC and must explicitly release 
the area with a FREEWA macro. 

The amount of space requested on a GETWA macro call all will be "rounded 
up" to the size of the smallest GETWA area defined which is as large 
or larger than the amount of space requested. (For example, sizes 8, 
48, 96, and 1024 were generated and the request is for 680 bytes, the 
request will be satisfied with a 1024-byte block.) 

When a GETWA is executed for a valid size area and all allocated blocks 
of that size are in use, the GETWA program will allocate additional 
space to satisfy the request. The additional The additional space 
will always be allocated in multiples of 2K and divided (if necessary) 
into blocks of a size that would otherwise be used to satisfy the 
request. The space, thus allocated, may be automatically released by 
a subsequent FREEWA when it is determined that there are sufficient 
free blocks of that size do not require immediate expansion again and 
an entire 2K block (or multiple) is not in use. This dynamic expansion 
of GETWA space will ensure that storage space is available as required. 
However, for performance considerations, the size of each GETWA area 
and the number of blocks defined for each size should approximate their 
actual usage during the realtime execution of an application. This 
will minimize both the CPU overhead and the amount of "wasted" storage 
areas. 

GETWA storage area that has been obtained by one task may be passed to 
another task through the task management routines. The GETWA storage 
area may have been obtained originally via a GETWA macro call specifying 
TYPE=AP, AT, or PC and can be passed to another task by issuing a PATCH 
macro call of the form 

PATCH FREE=( I AP I , address),... 



where "address" is the address of the GETWA storage and "AP" or "AT" 
indicates the GETWA queue to which the GETWA storage is to ba chained 
on the receiving task (i.e., PATCHed task). 

An AP request causes the storage to be freed whenever the work queue 
element built in response to this PATCH is completed. An AT request 
causes the storage to be freed whenever the PATCHed task is terminated. 
In this respect, an AP or AT request is analogous to the PATCHed task 
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acquiring the storage area by issuing a GETWA TYPE=AP or AT, 
respectively. 



Note that if the PATCHing task receives a return code equal to or 
greater than 8 from the PATCH macro call, the PATCH cannot be executed, 
and the PATCHing task is responsible for freeing this GETWA storage 
area by executing a FREEWA macro call (eventhough the area may have 
originally been obtained by the PATCHing task through the issuance of 
a GETWA TYPE=AP or AT macro call) . 

If the PATCH is successful (return code less than 8), but the work 
queue built in response to the PATCH is later removed from the PATCHed 
tasks work queue chain before it can be executed, the storage area 
specified is freed by the Special Real Time Operating system when the 
work queue is purged eventhough the PATCH may have specified FREE= (AT, 
address). If the PATCH was successful, the PATCHing task must assume 
that the storage area passed has already been freed and no reference 
to that area should be made after the PATCH has been executed. 



DEFLOCK/LOCK 

The DEFLOCK/LOCK routines may be used in combination to define and 
reserve user specified resources without incurring the overhead of th*^ 
ENQ/DEQ routines. 

Each resource to be reserved must be defined to the Special Real Time 
Operating System by a DEFLOCK macro call (TYPE=GET) . This macro call 
will cause a Special Real Time Operating System control block to be 
built describing the resource. The name of the resource will be 
returned in register 0, and the address of the new control block will 
be returned in register 1. This control block address must be specified 
whenever reserving a resource with a LOCK macro call. Once the control 
block has been defined, the address of the control block can be obtained 
by a DEFLOCK macro call (TYPE=FIND) . After all processing for a 
particular resource has been completed, the control block may be 
released by a DEFLOCK macro call (TYPE=REL) . Note that once the control 
block has been released, it must be redefined by a DEFLOCK macro call 
(TYPE=GET) before that resource can be reserved again by a LOCK macro 
call. 

A LOCK macro call (rYPE=LOCK) is used to reserve exclusively a resource 
that has been released previously by a DEFLOCK macro call. If the 
resource is unavailable at the time the LOCK macro is executed, the 
requesting task is placed in a WAIT state until that resource becomes 
available. A LOCK macro call (TYPE=0NLOCK) is used to release control 
of the resource. Note that the LOCK macro call used to release the 
resource must be executed from the same task that executed the LOCK 
macro that reserved the resource. If a Special Real Time Operating 
System task (i.e., a PATCHed task) is DPATCHed or ABENDS before 
releasing the resource, the Special Real Time Operating System exit 
routine will release the resource for that task. However, if a 
non-Special Real Time Operating System task (i.e., an ATTACHed task) 
returns or ABENDS before releasing the resource, the LOCK will remain 
set indefinitely. 
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PAGE FIX 



The Special Real Time Operating System provides a facility to allow 
users to 'fix' specific storage locations- To fix the storage, the 
user must create array DPPXFIX and put in it the names or numbers of 
arrays to be fixed and/or load modules to be fixed. Program DPPIPFIX 
will then process array DPPXFIX and LOAD the load modules and fix the 
virtual storage occupied by the specified arrays and load modules- 
No attempt should be made to fix the storage for load modules which 
are link-edited as other than REENTBANT. The page fix function, when 
applied to load modules, operates by executing a LOAD macro to bring 
the module into storage and determine the address and length of the 
module- This LOAD is independent of the LOAD that is executed by the 
Special Real Time Operating Task Management or a LOAD, LINK or ATTACH 
executed by a user program. The result of this sequence is that if 
the module is not reentrant, each execution of the LOAD for a given 
module will bring into storage a separate copy of the module. Even 
though a non- reentrant load module may be fixed, the copy which is 
fixed cannot be accessed by normal means. 



The format of the array named DPPXFIX is; 
1 W0RD-»-M-2 WORDS -*-!-«•- 2 WORDS - 



LLL 



NNNNNNNN 



00000000 



FFFFFFFF 



ARRAY DPPXFIX 

vfhere: 

T = Type of fix request 
L = load module 
A = named array 
N = numbered array 
C = control block 

LLL = Length of the fix request; zero indicates fix all storage 
occupied by the module or arra y- 

NNNNNNNN = The left justified name of the load module or named 

array to be fixed or the array number of the numbered 
array to be fixed in the first word followed by a word 
of zeros- For control block requests, the left justified 
name must be 'CBGET' to indicate that CBGET storage is 
to be fixed; 'GETWA* to indicate that GETWA storage is 
to be fixed; or 'USEEcccc* to indicate that a user 
control block is to be fixed- 
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0000000 = Each item must contain two words of zeros to be used by 
the page fix routine. 

The following is an example of the control statements required to create 
a DPPXFIX array. 

#/DPPXOCTL AR EA=D BDEF , I NPOT=* , OPT ION= EEPL 



ARRAY NAME=DPPXFIX,INIT=YES 

* Request 1 

A ITEM TYPE=C,INIT=« L» 

B ITEM TYPE=A,LEN=3,INIT=0 

C ITEM TYPE=C,INIT=' DPPI NIT1 ' 

D IT^M TYPE=F,RPT=2 

* Request 2 

E ITEM TYPE=C,INIT=« N« 

F ITEM TYPE=^A,LEN=3,INIT=50 

G ITEM TYPE=F,INIT=7 

H ITEM TYPE=F,RPT=2 

* Request 3 

I ITEM TYPE=C,INIT=» A' 

J ITEM TYPE=A, LEN=3,INIT=150 

K ITEM TYPE=C, INIT=» AA « 

L ITEM TYPE=F,RPT=2 

* List Terminator 

M ITEM TYPE=F, INIT=- 1 

* Request 4 

M ITEM TYPE=C,INIT='C« 

N ITEM TYPE= A,LEN=3, INIT=0 

0 ITEM TYPE=C,INIT=» CBGET' 

P ITEM TYPE=F, RPT=2 

* Request 5 

Q ITEM TYPE=C,INIT='C' 

R ITEM TYPE= A, LEN=3, NAME=ULEN 

S ITEM TYPE=C,INIT=« USERXYZI • 

T ITEM TYPE=F, NAME=UST ART 

U ITEM TYPE=F,INIT=0 



The above example creates an array named DPPXFIX for storage at 
initialization time and consists of: 

1. A fix request for all (ITEM card B) of load module (ITEM card 
A) named 'DPFINITI* (ITEM card C) . 

2- A fix request for 50 bytes (ITEM card F) of numbered array (ITEM 
card E) number 7 (ITEM card G) . 

3- A fix request for 150 bytes (ITEM card J) of named array (ITEM 
card I) named AA (ITEM card K) , 

4. A fix request for all (ITEM card N) CBGET storage (ITEM cards 
M and 0) . 
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5. A fix request for a user defined control block (ITEM cards Q 
and S) . On this request, the final characters of the name 
field (ITEM card S) must be 'USER*. The last 4 characters are 
not used by the page fix routine and may be used to further 
identify the control block by the user. 

6. ITEM card M generates a fullword of binary ones to indicate the 
end of the array. 

Note: On a user defined control block, the user mus t supply the length 
(ITEM card R) and the starting address (ITEM card T) before 
PATCHing the page fix routine (DPPIPFIX) . By defining ITEM 
names for the length and start address, user PUTITEM macro calls 
could be used to fill in the array- 

With array DPPXFIX created, the user must either have a PATCH card in 
his input stream for EP=DPPIPFIX or have a program which PATCHes 
DPPIPFIX. 

It is also important to note that the user must terminate the realtime 
job step ¥ith a reply to the Input Message Processor (IMP) of the form 

r xx,CANCEL[, ] 

in order to release the pages that have been "fixed" by the Special 
Real Time Operating System. 

Note: It is recommended that all arrays being fixed should be created 
with a use count of one (USE=1), that the BNDRY parameter not 
be used and no other arrays be created "rfith a ose count of 1. 
Also, Array DPPXFIX must not be logged. If it is, a copy will 
be used which has non-zero for the two fullwords requested by 
page fix, and the page fix function will be bypassed. 
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TWO-PARTITION OPERATION 



Two-partition operation may be requested at the Special Real Time 
Operating system SYSGEN time via the TWOPART operand on the VS macro. 
This allows programs running under control of the Special Real Time 
Operating System to communicate with programs running under control of 
the Special Real Time Operating System in a different job step. This 
environment is created by starting a job step and invoking the Special 
Real Time Operating System initialization (PGM=DPPINIT) in each of two 
partitions. Through this procedure, one of the job steps is designated 
as the MASTER and the other as a SLAVE to it. The MASTER job step has 
complete Special Real Time operating System facilities included in it; 
the SLAVE has limited Special Real Time Operating System facilities in 
it, but has access to the facilities included in the MASTER partition. 

The MASTER and SLAVE job steps are run in separate partitions of the 
0S/VS1 system and, as such, run under different storage protect keys, 
affording the user some protection for his data base, etc., from 
routines in the SLAVE partition- To attain effective communication 
between the two partitions, fetch protect must not be included in the 
system. This allows the programs in either partition to fetch data 
from the other partition, but prevents inadvertent storage of data into 
the other partition. Services are provided whereby programs in a SLAVE 
partition can store data into the data base, which is included in the 
MASTER partition. 

Two-partition operation is initiated through normal Special Real Time 
Operating System initialization procedures with one additional control 
statement in each job's input stream. The MASTER job is designated by 
including the following control statement anywhere in the job's input 
stream- 
label MASTER SLAVE= jobname 

where: Label is optional and must start in column 1 

MASTER Specifies this is the MASTER job step 

SLAVE= Specifies the name on the job card (JCL) of the job which 
is to be the SLAVE job step. 

The SLAVE job is designated by including the following control statement 
any where in the SLAVE job's input stream- 
label SLAVE MASTER=jobname 

where: Label is option and must start in column 1 
SLAVE Specifies this is the SLAVE job step 

MASTER= Specifies the name on the job card (JCL) of the job which 
is to be the MASTER job step. 
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When initializing the system in this mode, both job steps must be 
started before the Special Real Time Operating System initialization 
can effectively proceed in either partition. When a RESTART WRITE 
statement is encountered in either partition, it must be included in 
both. The restart data sets are written only from the MASTER partition, 
but not before the SLAVE has completed the specified pre-restart 
processing. 

When the MASTER partition terminates, the SLAVE is terminated with a 
USER 041 ABEND by the STAE routine. When the SLAVS terminates, 
two-partition operations are stopped in the MASTER until the SLAVE is 
restarted. 

An attempt to start a SLAVE partition job when the MASTER job already 
has a SLAVE job executing will result in a user 4 1 ABEND for the second 
SLAVE job step. 

Services not documented in the following two-partition description will 
exist in both the partitions. 

Task Mana gement 

Both the MASTER and SLAVE partitions are provided Special Real Time 
Operating System task management services. 

The PTN= parameter on the macro calls allows the user to specify the 
target partition for his PATCH, DPATCH and REPATCH: 



If not explicitly specified on the macro call, the caller's own 
partition is the target partition for the macro. 

Note on the PATCH macro: 

a. The FREE= area must be in the partition, where the work represented 
by this PATCH will be executed and may not be used otherwise, 
because it is impossible to FREEMAIN storage in another than the 
own partition. For the same reason, FREE= is invalid if a PATCH 
goes to the other partition and REPATCH option is specified. 

b. The PRTY/PRTYLOC parameter, if used, must specify the name of a 
task in the same partition as the created task. 

While i't is not a Special Real Time Operating System restriction, 
consideration must be given to passing data area addresses across 
partition boundaries. The area cannot be stored into except by programs 
in the same partition as the area or by supervisor services. 

Task management control blocks will reside in both partitions as will 
the task management routines. However, if two--partition operation is 
desired, consideration should be given to the inclusion of certain task 
management routines in the Link Pack Area so that the same copy may be 
used for both partitions (see Coding and Performance Considerations) . 



Time Mana gement 

Both the MASTER and SLAVE partitions are provided Special Real Time 
Operating System time management services. The Special Real Time 
Operating System time and date are the same for both partitions. 



OWN 

MASTER 

SLAVE 

FIND 
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The PTN= parameter on the PTIME macro allows the user to specify the 
partition in which a routine will be executed as the result of the 
PATCH macro call (s) by the time management routines. 

The parameter 



PTIME ...,PTN 



is identical in form and function with the PATCH parameter (PTN=) and 
is also subject to all restrictions specified for cross partition 
PATCHes; 

Note that the time management routines and control blocks (PTQES) will 
reside only in the MASTER partition and, therefore, all resulting 
PATCHes will be issued from the MASTER partition. 



Data Base 

Both the MASTER and SLAVE partitions will be provided Special Real Time 
Operating System data base services. The Special Real Time Operating 
System data base will be the same for both partition. All data 
definition statements required to define the data base must be contained 
in the JCL for the MASTER partition job. The data definition statements 
relative to the data base are not required in the JCL for the SLAVE 
partition job and if present will be ignored. This includes the DD 
statements for the data base partitioned data set, all data base BDAM 
data sets, and all sequential data sets required for any DUMPLOG macro 
calls. Also, the DBR EF statement, if desired, must be included in the 
input stream for the MASTER partition's job. The VS resident arrays 
and all data base control blocks will reside in the MASTER partition. 
Therefore, it should be noted that the user in the SLAVE partition 
cannot store directly into the VS resident data base but must use the 
Special Real Time Operating System data base macro calls. 

All data base macro calls (i.e., GETLOG , POTARRAY, etc.) will be 
supported from the SLAVE partition except GET/PUTARRAY with the ADDRLST 
option and GET/PUTITEM with the ADDRLST option. A return code 16 will 
be issued for these requests from the SLAVE partition. 

Note: Data base macro calls issued from the SLAVE partition require 

the use of additional SVC routines to resolve the in terpartition 
communication problem and, therefore, will incur additional 
system overhead. 

The capability to define and reserve a resource will be provided for 
the SLAVE partition. However, partition LOCK/DEFLOCK routines will 
operate independently of each other; that is, a resource defined in 
one partition cannot be reserved via a LOCK macro call from the other 
partition. Cross-partition LOCK/DEFLOCK requests will not be supported. 



5!i2iicate Data Set Su pp ort 

Duplicate data set support is available to programs in both partitions. 
S data set pair which is DDSOPENed in one partition should not be 
accessed by programs in the other partition except by DDSOPENing it in 
both partitions. 



OWN 
SLAVE 
MASTER 
FIND 
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Realtime Messag e Handler 

All messages issued out of the SLAVE partition will be output from the 
MASTER partition. A message issued in the SLAVE partition will have 
an S affixed to the message when it is output. 

EXAMPLE: 

DPP001S 2:29:23:3 01/rEB/7U REAL-TIME MESSAGE 
The MSGDS DD card must be included in the JCL for each partition. 



Input Message Pro cessin g 

Input Message Processing (IMP) commands can be issued only to the MASTEJ 
partition, but Input Message Processing can accept IMP commands to the 
SLAVE partition. The parameter SLAVE will follow the IMP command word. 
The parameters passed to the processing program will follow SLAVE. 

EXAMPLE: 

» EX AMPLE, SLAVE, PAR AMI, PA RAM2,. .. PARAM2 0' 
EXAMPLE: IMP Code. 

SLAVE: Issue IMP command to SLAVE partition. 

PARAM: Parameters accepted by the processing program. 



Hata Reco rdin g and Playback 

Data recording and playback will run in both the MASTER and SLAVE 
partitions. The DRECOOT DD card must be included in the JCL for each 
partition. The DPBIN and SRTODUHP DD cards must be included in the 
JCL for each partition if Data Playback is to be run as a Special Real 
Time Operating System job- 



Rep ort Data Output Fa cility 

The report data output facility will run in both the MASTER and SLAVE 
parti tions. 



APPLICATION SERVICES 2-175 



SPECIAL REAL TIME OPERATING SYSTEM DEBOG GUIDE 

User programs which run under the Special Real Time Operating System 
and ABEND will appear in a storage dump to be ABENDing in DPPTMON 
because the user programs ate loaded by DPPTPMON which then branches 
to them. As a result, the user programs are not represented by a PRE 
on the TCB's active RB chain. They run under the PRB for DPPTPMON- 
Figure 2-33 shows how the Special Real Time Operating System and OS 
control blocks would look upon entry to a user program. 

The entry point of the program to which DPPTPMON gave control can be 
determined by looking bytes into the register save area pointed 

to by the TCBFSA field. using the ABEND PSH and the entry point, the 
user can determine the displacement into the failing program of the 
last instruction executed prior to the failure. The program name can 
also be found by locating the LPRB with this entry point on the LPRB 
chain. An alternate method of locating the failing program is through 
the TCBOSER-TCBXCWQ-WQLCB-LCBEPAD and LCBEPNAM chain. 

The TCBXNAME field of the TCBX will contain the task name (TASK=) of 
the task or DEPNDNT if this is a dependent task. 

For additional debug information, refer to the IBM 0S/VS1 D ebugginq 
Guide (GC2U-5093) . 
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CODING AND PERFORMANCE CONSIDERATIONS 



Certain considerations are normally made by a programmer when he is 
coding a program which will execute in a batch processing environment. 
However, additional considerations should be made when coding programs 
for a realtime environment. These additional considerations should be 
evaluated to determine if they will impact execution efficiency and 
system reliability. Some of these considerations are discussed on the 
following pages. 

The Special Real Time Operating System tasks and user programs execute 
as subtasks; as a result, virtual storage gotten for a subtask by an 
0S/VS1 GETMAIN or REGHAIN must be explicitly freed. If it is not, the 
storage is lost and causes fragmentation within the partition. Storage 
which the Special Real Time Operating System GETWA routine gets for 
TYPE=PC must also be explicitly freed by FREEWA or this storage is also 
lost. OS/VSI task management routines build control blocks with fixed 
PQA in a partition. If this PQA storage must be expanded during a 
realtime run, it may cause fragmentation of the partition. One 
consideration to help avoid fragmentation by PQA is to get the maximum 
number of TCBs which will be required for the realtime run through the 
use of the TCB control statement. 

Programs coded for the Special Real Time Operating System should be 
coded as reentrant programs, if possible, to avoid having multiple 
copies in storage and to improve the OS/VSI paging frequency. Also, 
because the Special Real Time Operating System PATCH monitor loads then 
branches to user programs, no user program which is to be PATCHed should 
ever issue EXIT (SVC3) or XCTL. 

Careful consideration should be given to the amount of storage which 
is to be fixed by the page fix routine (DPPIPFIX) , because page fixing 
has an adverse effect on the paging rate and may lead to thrashing. 

Dependent Special Real Time Operating System tasks are initiated, 
execute once only, and are terminated. The additional overhead of 
initialization can be avoided by using independent tasks. This, 
however, causes the program (if reentrant) to remain in virtual storage 
and to maintain its resources. Careful consideration should therefore 
be given to whether user programs should be executed as dependent or 
independent tasks. Also, programmers who code programs to execute as 
independent tasks that open DCBs should be aware that the DCBs will 
not be closed after an execution of the program and that they will not 
be closed by a DPATCH. This nay cause problems, since the TCB may be 
used by another Special Real Time Operating System task. This is also 
true of tasks which issue STIMER, then continue and never issue a TTIMER 
CANCEL for the STIMER, 

If there is frequent use of GETWA blocks greater than 2K, the paging 
rate in the system may be improved if the user executes an OS/VS PGRLSE 
macro on the GETWA area prior to the FREEWA of the area. 

Non-Special Real Time Operating System tasks (created by ATTACH) which 
reserve a resource via LOCK then ABEND, will not cause the Special Real 
Time Operating System ETXR routine to have the resource freed. 

If the Special Real Time Operating System job step is to be terminated, 
careful consideration should be given to the method by which it is 
terminated, because the Special Real Time Operating System STAE routine 
will not be entered for ABEND codes 122, 13E, 222, 322, 522, or 722. 

Programs which include the Special Real Time Operating System macro 
statements can be made more efficient and independent of the user SVC 
numbers generated by coding the DCVTR or DCVTLOC on Special Real Time 
Operating System macro statements. 
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The SISGBN time interval for the Special Real Ti»e Operating System 
time update routine (PTIHE= operand on the 7S STSGEN macro) should be 
■ade as larqe as practical in order to reduce the Special Real Tiae 
Operating System time management overhead. This is also true of data 
base logging overhead, which can be reduced by specifying as larqe as 
practical logging frequencies (LOGFPEQ operand of LOG macro for the 
Special Real Tine Operatino Systea SYSGEN) . 

& logical BLOCK of a DA array will be represented by a physical block 
in the direct access data set. As a result, the DA array block size 
should be as large as possible for aore efficient use of direct access 
storage. 

Initialization using a DBREP HO statement will result in the loss of 
previously logged data. 

Blocked arrays should be used whenever possible because they may then be 
used as either DJ or IS resident arrays. Number arrays require less 
overhead than naaed arrays when accessed through GETARRAT, PUTARRAY, 
GETBLOCK, or PUTBLOrK macros. ?lso, when a GETTTEH or PUTITEH macro 
is executed, I/O processing is invoked to resolve itea naaes to storage 
addresses. Therefore, it may be aore efficient to resolve the itea naaes 
at one time and to make subsequent accesses to the same items via these 
addresses rather than via the itea naaes. 

Programs should use data base macros to access the data base to ensure 
the integrity of the data base and to allow the program to be 
independent of the partition in which it executes (1ASTER or SLAVE). 

QPOS=DPATCH is not allowed if the task name represents a QH. 

EP= (name DELETE) will remove the load module for the QP under which the 
work queue is processed and not necessarily for all QPs that may have 
processed work froa this QH. 

The TCBX address returned from the PATCH aacro is the address of the 
QH TCBX. If the user is using this address to interrogate the progress 
of the work, the inforaation that is picked up aay not be aeaningful. 

PRTY= and QL= will never be aeaningful when the NAnB= specifies a QH. 
These parameters are established when the QH is defined. 

If several PATCHes are executed with the PROBL or other work space to 
be freed by the PREE= paraaeter on the last PATCH, the last PATCH 
executed may not be the last to complete processing. The result may 
be that the area is freed before the last use of the area. This can 
happen when the PATCH is executed by the PTIHE function. 

An immediate DP4TCH (DPATCH TYPE=I) to a QP will terminate the work 
currently active, but will not delete the task. All other DPATCHs for 
a QP and all OPATCH's for a QH are disallowed. 

GETWA TYPE=AT executing under a QP or GETSA areas passed via PATCH to 
the AT chain of a QP will never be freed by Special Real Time Operating 
System (a QP can never be DPATCHed) . 

If the user were to set a LOCK while processing one Work Queue and 
return leaving the LOCK set intending the release the LOCK when 
processing the next work queue, it aay not work because the next work 
queue may be processed under a different task (QP) and the LOCK must 
be released by the saae task which it was set. 
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SPECIAL REAL TIHE OPEBATIHG SYSTEM ONLINE HACROS 

For conveaience^ all online aacros and their calling sequence are 
asseabled in alphabetical order by aacro naae in the folloffing pages. 
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BEGIN 

The BEGIN macro provides standard OS linkage conventions for reentrant 
or non-reentrant routines. In general, the BEGIN statement is designed 
to: 

• Identify and label the main control section or entry point address 

• Save the calling program's general purpose registers. 

• Establish main control section addressability. 

• Prepare a save area. 

• Define register usage through the EQDATE macro. 

The following options are available for the BEGIN macro example: 

Note: All register specifications should be absolute numbers rather 
than equated symbols (i.e., 13 rather than E13). 

Programs using the BEGIN macro must be provided a higher save area by 
the calling program. 



symbol] BEGIN [csect name] 

,ENTRY= symbol 
,BASE= (reg, [label] ) 
,ADDB=(reg 1, [reg 2,. . .,reg 

'none 



, SAVE= 



(reg 1 , reg 2 



[/ symbol 
,SAVEA= I (GETMAI 
\ \GETWA 



■GETMAIN| [, label] 



n] )] 

)|] 



, LV= number 
, SP=number 
ENTER=PATCH 
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CSECT name 

The name to be given to the main control section- 



ENTRY= 

The label name to be given to the first instruction and to be declared 
via the ENTRY assembler instruction. 



BASE= 

Specifies the general purpose register to be used as the initial main 
control section base and the label to be given to the point of zero 
displacement. Note that if no save area is requested and "reg" is 
omitted, register 15 is assumed. If a save area is to be assembled 
internally and a "reg" is omitted, register 13 is assumed. If a save 
area is to be obtained via a GET MAIN or GETWA and "reg" is omitted, 
register 12 is assumed. 



ADDB= 

Specifies additional main control section bases to be initialized at 
zero displacement + 4096, zero displacement ♦ 2*4096, etc. 



SAVE= 

Indicates range of general purpose registers to be saved in the 
caller's save area. If omitted, registers 14 through 12 are saved. 



SAVEA= 

Specifies the type of save area to be used by the program. 
"SAVEA=GETMAIN" indicates that a GETMAIN is to be issued to obtain 
the save area. " S A VEA=GETWA" indicates that GETWA is to be issued to 
obtain the save area. "SAVEA=sy mbol" indicates that the save area is 
to be expanded within the program. Both S AVEA=GETMAIN and SAVEA=GETWA 
will result in reentrant code being generated. SAVEA=symbol is 
non- reentrant. Register 13 will contain the address of the save area. 
If omitted, no save area will be reserved. The "label" operand, if 
specified, will be used as the name of the DSECT describing the work 
area. 



LV= 

The length, in bytes, of the storage area to be obtained via a GETMAIN 
or GETWA. If SA VE A=GETMAIN or GETWA and LV= omitted, 72 bytes will 
be obtained. If GETWA is specified and the LV= value is greater than 
the largest GETWA size allocated, a system ABEND (probably 0C4) will 
occur within the code expanded by the BEGIN macro. 

SP= 

The number of the subpool from which the save area is to be 
obtained. If omitted, 0 is assumed and when executed under 0S/VS1, 
the subpool specification will default to 0. 

ENTER=PATCH 

Specifies that the program is always entered via a PATCH interface. 
This operand is used only when SAVEA=GETWA is specified. If this 
operand is omitted or if anything other than PATCH is coded, it is 
assumed that the program may be entered by a linkage other than PATCH. 
Dse of this parameter allows a smaller macro expansion. 
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CHAIN 

The CHAIN macro provides the facility for allowing multiple tasks to 
modify the same control block chains without the necessity of the user # 
issuing ENQ/DEQ or getting himself into a disabled state. 



[symbol] 



CHAIN 



[ADD, ] 

[remove, J 

[address 



, BLOCK 



J (r) 



(address 
(FIRST \ 



r,Pos= {last 1 
^ ^disp. ) 

[ 



ECB= 



((address 
, DCVTR= r 



r| (r) jl 1 

L( condition code ) J )J 



,DCVTLOC= 1 

(address 



[mf=l1 [mF=(eJ (r) f) 
(addressi - 



where *r* is a general purpose 
register, 2-12. 
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ADD 

If the control block specified is to be added to the chain. This 
value is the default value. 

REMOVE 

If the control block is to be removed from the chain. 

ORG = 

Specifies the origin of the chain^ This address must be in the origin 
of the chain and not in a previous control block in the chain- The 
reason is that the task could lose control, and the chain could be 
modified so that the "previous" control block address would no longer 
be valid when the task regained CPU control. However, since CHAIN 
executes disabled, this cannot occur when the origin of the chain is 
used. Any RX-type instruction address format is valid. 

BLOCK= 

Address of control block to be added or removed. An RX-type 
instruction address format is valid. 

POS = 

Only valid with ADD and specifies at which end of the chain to insert 
vhe block. FIRST implies the end of the chain nearest the origin. 
LAST implies the end of the chain farthest from the origin. 'disp' 
is the displacement into the block of a fullword containing a value 
to be used as a comparand. This value is used to insert the block in 
an increasing collating sequence relative to other blocks on the chain. 

INDEX= 

Specifies the offset in the control block to the chain point 
(fullword) , Note that INDEX does not apply to the ORG address 
i.e., ORG always specifies the exact address of the fullword containing 
the address of the first control block. The index may be loaded in 
a register, r, and INDEX=(r) specified. If this parameter is omitted, 
the chain pointer is assumed to be the first word of the block. 

ECB = 

Specifies an ECB to be posted with the specified completion code after 
the chain is modified. Any RX-type insturction address format is 
valid for the ECB address. The condition code can be loaded in a 
register and specified as ECB= (addr, (r) ) - 

DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC= (r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses that has the address of a 4-byte core location that 
contains the address of the XCVT. 

DCVTLOC=address 

Where 'address' is the label of a 4- byte core location that contains 
the address of the XCVT. 

MF= 

The list or execute forms of the CHAIN macro which are generated by 
specifying MF=L or MF=(E, address). 
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CHAIN Return Codes: 
Decimal 



Code Descript i on 

00 Successful completion. 

04 REMOVE block address not found in chain. When this 

condition exists, the ECB will not be posted. 

08 Invalid address in list. When this condition exists, 

the ECB will not be posted. 

12 ECB specified had been previous posted. 



APPLICATION SERVICES 2-185 



DDSBLDD 



The DDSBLDL macro is used to construct a note/point list of a DDS the 
same as BLDL for a standard OS data set. Return codes vill be the same 
as from the OS BLDL macro. 







r(.DCVTR=(r) 






[ symbol | 


DDSBLDL 


(OS parameters) j 1 ^""^ ! 










L ( ,DCVTLOC=(address) 













The OS parameters are the same as in BLDL; that is, DCB address, list 
address. 

DCVTR=r 

Where 'r* is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC=(r) 

Where 'r* is the general purpose register (2-12) enclosed in 
parentheses, having the address of a 4-byte core location that contains 
the address of the XCVT. 

DCVTLOC=address 

Where 'address* is the label of a 4-byte core location that contains 
the address of the XCVT. 
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DDSCLOSE 



The DDSCLOSE macro is used to close a DDSDCB. Only one DDSDCB can be 
specified and TyPE=T is not valid. 



[symbol] 




r(,DCVTR«(r) / . 






DDSCLOSE 


(OS parameters) \ I 1 ^'"^ 1 








L (,DCVTLOC= (address) 







The valid OS parameters are DDSDCB address and MP=operand. 
DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC= (r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses, that has the address of a 4-byte core location that 
contains the address of the XCVT- 

DCVTLOC=address 

Where 'address* is the label of a U-byte core location that contains 
the address of the XCVT, 
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DDSDCB 



The DDSDCB macro is used to define the DCS for a Duplicate Data Set. 
The DDNAME specified in the macro should be the same as the name field 
of the DDSNAMES card in the DDSCTLIN input stream. 



[symbol] 



DDSDCB 



( OS parameters ) 



This macro is coded identically to the OS DCB macro with the following 
notes: 

• DSOEG must be PS, PO, or DA, 

• OPTCD can be omitted or W, E, or F- 

• Multi-tracking cannot be specified. 

• Only the following parameters are valid: BLKSIZE, DDNAME, DSORG, 
KEYLEN, LPECL, MACRF, NCP, OPTCDr RECFH, and SYNAD. 



The DDSDCB ma 
(DDS) facilit 
Whenever the 
the address o 
a subset of t 
access method 
manual (GC26- 
operand liste 
listed in the 
the operand i 
or extension 



cro performs the same function for the Dupli 
y as the DCB macro performs forthe 0S/VS1 da 
address of a DCB is required with the other 
f a DDSDCB must be specified. The operands 
he DCB operands. The valid operands are lis 
Refer to the OS/V S1 Data Manaqeme nt Macro 
3793) for a detailed description of the oper 
d below does not have any restrictions other 

DDS description in Chapter 2, the field to 
s left blank. If the field is not blank, a 
to the 0S/VS1 options is noted. 



cate Date Set 
ta management. 
DDS macros, 
of DDSDCB are 
ted below by 

Instruc tion s 
ands. If an 

than those 
the right of 
restriction 



Operands valid with BDAM are: 

• BLKSIZE= 

• DDNAME=ddsname 

• DSOEG=DA only 

• EODAD= 



MACRF= 

OPTCD=W/R, F only 
RECFM= 



• KEYLEN= SYNAD= 

• LRECL= DEVD=DA 
Operands valid with BSAM and BP AM are: 

• BLKSIZE= LRECL= 

• DDNA«E=ddsname MACRF= 

• DEVD=DA only NCP= 

• DSORG = PS and PO OPTCD=(W) 

• EODAD RECFM- 

• KEYLEN= SYNAD* 



Note: Invalid DCB options or operands must not be specified in the DD 
card DCB^operand. 
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DDSFIND 



The DDSFIND nacro is used to perform that same function as FIND but 
for a DDSDCB- Return codes nill be the same as from the OS FIND macro. 



symbol ] 



DDSFIND 



pj.DCVTR=(r) |-| 
L(,DCVTLOC=(address j J J 



(OS parameters) 



The OS parameters are the same as in OS FIND, that is, DCB address 
member/name/point list, type. 

DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XC?T. 



DCVTLOC= (r) 
Where 'r' is the general purpose 
parentheses that has the address 
contains the address of the XCVT 



register (2-12) enclosed in 
of a 4- byte core location that 



DCVTLOC=addrecs 

Wl.-ere 'address* is the label of a U-byte core location that contains 
the address of the XCVT. 
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DDSOPEN 



The DDSOPEN macro is used to open a DDSDCB. Only one Only one DDSDCB 
can be specified and, for update option, the task opening the DDSDCB 
must maintain exclusive control over it. 



The valid OS parameters are DDSDCB address, OPEN option and MF=. 

DCVTR=r 

Where 'r' is the general purpoi« register (2-12) that contains the 
address of the XCVT. 

DCVTLOC=(r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses, having the address of a U-byte core that contains the 
address of the XCVT. 

DCVTLOC=address 

Where 'address* is the label of a 4-byte core location that contains 
the address of the XCVT. 



[symbol] DDSOPEN (OS parameters) 




,DCVTR= r / 

(r) 

,DC VTLOC = (address 
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DDSSTOW 



The DDSSTOW macro is used to STOW a member of a partitional DDS. Return 
codes will be the same as from the OS STOW macro. 



[symbol] 



DDSSTOW 



(OS parameters) 



,DCVTR= r 

( (r) ) 
DCVTLOC=(address ) 



I] 



The OS parameters are the same as in OS STOW; that is, DCB address, 
member-name, and type. 

DCVTR=r 

Where «r' is the general purpose register (2-12) that contains the 
address of the XCVT, 

DCVTLOC= (r) 

Where «r» is the general purpose register (2-12) enclosed in 
parentheses, having the address of a U-byte core location that contains 
the address of the XCVT. 

DCVTLOC=address 

Where 'address* is the label of a 4- byte core location that contains 
the address of the XCVT. 
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DEFLOCK 



Each resource to be reserved must be defined to the Special Real Time 
Operating System by the use of a DEFLOCK macro. The DEFLOCK macro will 
cause a control block to be built describing the resource. The name 
of the resource will be returned in register 0 and the address of the 
control block will be returned in register 1. This control block 
address must be used whenever reserving a resource with the LOCK macro. 
After all processing for a particular resource has been completed^ the 
control block may be released by another DEFLOCK macro. Once the 
control block has been released, it must be re-defined by a DEFLOCK 
macro before that resource can be reserved again. In the case of 
two-partition operation, separate lock controls are maintained for each 
partition. Thus a program cannot use a lock control block created in 
the other partition. 

The DEFLOCK macro may also be used to obtain the address of a previously 
defined lock control block- 



The following operands are available for the DEFLOCK macro: 



[symbol] 



DEFLOCK 



I name ; 



TYPE= 



,DCVTR= r 




( (r) 
.1 ,DCVTLOC=\ address 



i! 



(r) 

name 

Is the positional operand that defines the 4-byte resource name. If 
(r) is specified, the general purpose register (0 or 2-12) contains 
the resource name. 



TYPE= 

Is used to indicate that a resource control block is being defined 

(TYPE=GET) or released (TYPE=REL)« The address of the control block 

on TYPE=GET requests is returned in register 1. 

A DEFLOCK with a TYPE=FIND option vil\ cause the address of a 
previously defined lock control block to be returned in register 1. 

DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XCVT- 



DCVTLOC= (r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses that has the address of a 4- byte core location that 
contains the address of the XCVT. 



DCVTLOC=address 

Where "address' is the label of a 4- byte core location that contains 
the address of the XCVT. 
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when control is returned, register 15 contains one of the following 
return codes: 

Decimal 



Cod e Descriptio n 

0 Successful completion, 

U Resource already defined. Register 1 contains the 

previously defined control block address. 

8 Job step is not a Special Real Time Operating Syste-i 

task . 

12 Resource not previously defined, (Valid only for 

TYPE=REL and TYPE=FIND requests,) 
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DPATCH 



An independent task is created to be executed continuously over an 
indefinite time period. When an independent task is no longer required, 
it can be deleted by use of the DPATCH macro. Since the task may have 
several elements on its work queue an unconditional DPATCH does not 
allow these elements to be executed. Any ECBs associated with the work 
queue elements are posted with a DPATCH completion code. The DPATCH 
can be specified as W, which prevents losing any work queues, or it 
can be specified as conditional, which deletes the task only if it is 
dormant, A DPATCH immediate can be used to abnormally terminate a task 
that executes a long running program (e. g. , report- routine) . DPATCH 
of a queue holder is not allowed. Only TYPE=I or A is allowed to a 
queue processor. 



[symbol] 



DP ATCH 



Lname J 



,TYPE= 




f Oil 
I MASTER 

SLAVE 

FIND 



,PTN= 



,DCVTR= (r) 



(r) 

,DCVTLOC= 1 address) 



Where 'r' is a general purpose register (2-12) 
I \ 



name 

:s a 1 to 8 character name of the task to be deleted. If register 

orm is specified, the register contains the address of the task name. 
If omitted, the current task is to be deleted. 



ry?E= 

If I is specified, the task is to be deleted immediately. It will be 
abnormally terminated with a user abend code of 65. However, a WQE 
that was queued wit i QPOS=DPATCH will still be executed as part of 
the cleanup processing. 

If U is specified or the operand is omitted, the task specified is to 
be deleted unconditionally. Any work queue to the Any work queue 
to the task is posted as deleted. The current WQE, if executing, is 
allowed to complete. If C is specified, the specified task is deleted 
only if its work queue is currently empty. If W is specified, the 
task is deleted when the work queue becomes empty. This does not 
prevent work being queued to the task. If register form is specified, 
the register contains a numeric code of 0, U, 8, or 12. A numeric 
code of 0 corresponds to a TyPE=a request, U corresponds to a TYPE=C 
request, 8 corresponds to a TYPE=W request, and 12 corresponds to a 
TYPE=I request. If A is specified, the program executing under the 
task will be abnormally terminated with use code 65. The task will 
not be deleted as an independent task and any work queues that are 
awaiting execution will not be deleted. 
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PTN = 

In two-partition operation, this operand defines the target partition 
for the DPATCH. OWN means that the target partition is the partition 
that executes the DPATCH; MASTER defines the MASTER partition as the 
target partition. SLAVE defines the SLAVE partition as the target 
partition; if SLAVE is coded and two-partition operation is not 
initialized (no MASTER/SLAVE control cards in the SYSINIT input 
stream) , the DPATCH will be rejected and a return code passed back in 
register 15. FIND causes the SVC to search for the task in its own 
partition first, then in the other partition and the first one found 
will be DPATCHed, 

If register form is used to specify the task name and the PTN= operand 
is not specified, the high-order byte (byte 0) of the register also 
defines the target partition. The same bits are used as in the PATCH 
supervisor list (SUPL) , and they have the same meaning. 



SUPLPTNS=1 
S0PLPTNM=1 
both zero 
both one 



PTN= SLAVE 
PTN= MASTER 
PTN=OHN 
PTN=FIND 



However, if the PTN= operand is specified, the expansion of the macro 
will insert the proper bit into the high-order byte. 

DCVTR=r 

Where »r' is the general purpose register (2-12) that contains the 
address of the" XCVT. 

DCVTLOC=(r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses having the address of a U-byte core location that contains 
the address of the XCVT. 

DCVTLOC=address 

Where 'address' is the label of a 4-byte core location that contains 
the address of the XCVT. 

When control is returned, register 15 contains one of the following 
return codes: 
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Decimal 
£o^e 

0 

4 

8 

12 No DPATCH 
16 No DPATCH 
20 No DPATCH 
22 No DPATCH 
24 No DPATCH 
28 No DPATCH 



Successful completion. 

Task was already DPATCHed=W 

Task tias already DPATCHed-U 

Task is not dormant (DPATCH=C only) 

Task is being removed 

Task name not found on independent task chain 
PTN=SLAVE requested but not initialized 
Invalid parameters passed. 

Task name specified a queue processor and type 
not I or A or task name specified a queue holder. 
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DPPXBLKS 



The DPPXBLKS macro generates DSECTs for various Special Real Time 
Operating System and 0S/VS1 control blocks- define requested control 
blocks. When a keyvord is omitted, the When a keyword is omitted, the 
control block associated with that keyword is not expanded. With the 
exception of the "TYPE-" parameter, any non-blank character is 
acceptable as the keyword operand - 

The following operands are available for DPPXBLKS- 



[symbol ] 


DPPXBLKS 


1^ TYPE= 


/dsect ) 1 












(CSECT / J 










[ , REGS= ] 












[ ,TASK=] 


[ ,TCBX=] 


[ ,TMCT=] 


[,WQ=] 






[ ,LCB=] 


[,GFCB=] 


[,GFMB=] 








[ ,TIME=] 


[,PTQE=] 


[ ,TIMED=] 


[,PTIMEL=] 






[ ,DDS=] 


[ ,DDSDA=] 




i 
\ 






[/0S=] 


[ ,TCB=] 


[,CVT=] 


[,RB=] 






[ ,SRTOS=] 


[ ,XCVT=] 


[ ,SCVT=] 


I 






[,SUPL=] 


[ , REPL= ] 










[/DB=] 


[,ALTPRI=] 


[ ,ALTSEC=] 


[,DADD=] 






[ ,DIRB=] 


[ ,DIRR=] 


[ ,DMPHDR=] 


[,PBT=] 






[ ,LOGCB=] 


[ ,LOGHDR=] 


[ ,DACNTL=] 


[LOCK=] 






[,MSG=] 


[,IMP=] 


[ ,DREC=] 


[ ,GFMB] 
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TYPE= 

Used in conjunction with the TCBX, TMCT, WQ, LCB, GFCB, and PTQE 
parameters and indicates that the control block is to be expanded as 
a DSECT or CSECT. If omitted, DSECT is assumed. 



EEGS= 

Indicates that the macro is to be expanded to provide register equates, 
TASK= 

Used to indicate that the control blocks related to task management 
are to be expanded as DSECTs (CSECTs). These are the TCBX, TMCT, VQ, 
LCB, and GFCB control block. 

TCBX= 

Used to indicate that the control block for the TCB extension (TCBX 
is to be expanded as a DSECT (CSECT). 

TMCT= 

Used to indicate that the control block for the task management control 
table (TMCT) is to be expanded as a DSECT (CSECT), The control block 
for the GETWA/FREEWA main block (GFMB) will also be expanded. 

WQ= 

Indicates that the control block for the work queue (HQ) is to be 
expanded as a DSECT (CSECT) . 

LCB = 

Indicates that the control block for the load control block (LCB) is 
to be expanded as a DSECT (CSECT) - 

GFCB= 

Indicates that the control block for the GETWA/FREEWA control block 
(GFCB and GFBE) are to be expanded as a DSECTs (CSECTs), 

TIf!E= 

Indicates that the control blocks PTQE, TIMED, and PTIMEL, related to 
time management are to be expanded as DSECTs (CSECTs). 

PTQE= 

Indicates thct the control block for the PTIME queue element (PTQE) 
is to be expanded as a DSECT (CSECT) . 

TIMED= 

Indicates that the time array DSECT (TIMED) is to be expanded- If 
"TIMED-PTIME" is specified, the control blocks used in time management 
are also expanded. 

PTIMEL= 

Indicates that the DSECT describing the PTIME input parameter list 
(PTIMEL) is to be expanded. 

Eas= 

Indicates that the DSECT (DDSDA) for duplicate data sets is to be 
axpanded. 

r )SDA= 

Indicates that the DSECT describing the duplicate data set data area 
(DDSDA) is to be expanded. 

os= 

Indicates that certain OS control blocks are to be expanded as DSECTs. 
These are the CVT, TCB, and RB control blocks. 
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CVT = 

Indicates that the DSECT that describes the OS communications vector 
table (CVT) is to be expanded. 

TCB= 

Indicates that the DSECT that describes the OS Track Control Block 
(TCB) is to be expanded. 

RB= 

Indicates that the DSECT that describes the OS Request Block (RB) is 
to be expanded. 

SRTOS= 

Indicates that the Special Real Time Operating System communications 
table are to be expanded as DSECTs. These are the XCVT and SCVT 
tables. 

XCVT= 

Indicates that the DSECT that describes the primary Special Real Time 
Operating System communication table (XCVT) is to be expanded. 

SCVT= 

Indicates that the DSECT that describes the secondary Special Real 
Time Operating System communication table (SCVT) is to be expanded. 

REPL= 

Indicates that the DSECT that describes the PATCH supervisor input 
parameter list (SUPL) is to be expanded. The PATCH problem program 
input parameter list (PROBL) is also expanded. 

SDPL= 

Indicates that the DSECT that describes the PATCH supervisor input 
parameter list (SOPL) is to be expanded. The PATCH problem program 
input parameter list (PROBL) is also expanded, 

DB= 

Indicates that the control blocks for the data base are to be expanded 
as DSECTs. These are the ALTPfil, ALTSEC, DADD, DIRB, DIRR, DMPHDR, 
PBT, LOGCB, and LOGHDR. 

ALTPRI= 

Indicates that the control block for the primary array location table 
is to be expanded as a DSECT. 

ALTSEC= 

Indicates that the control block for the secondary array location 
table is to be expanded as a DSECT. 

DACNTL= 

Indicates that the control block that describes the direct access 
array control record is to be expanded as a DSECT 

DADD= 

Indicates that the control block for the direct access DD name table 
is to be expanded as a DSECT, 

DIRB= 

Indicates that the control block that describes the BLDL directory is 
to be expanded as a DSECT, 

DIRR= 

Indicates that the control block that describes the PDS directory is 
to be expanded as DSECT. 
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DMPHDR= 

Indicates that the control block that describes the DDMPLOG header is 
to be expanded as a DSECT. 

PBT= 

Indicates that the control block that describes the Page Boundary 
Table is to be expanded as a DSECT, 

LOGCB= 

Indicates that the control block that describes the log control block 
is to be expanded as a DSECT. 

LOGHDR= 

Indicates that the control block that describes the LOG header is to 
be expanded as a DSECT. 

LOCK= 

Indicates that the control block for the LOCK control block (LOCKCBLK) 
is to be expanded as a DSECT. 

MSG = 

Indicates that the control block for the realtime message handler is 
to be expanded as a DSECT- 

IMP= 

Indicates that the DPPXIMP array, input message processing control 
block, is to be expanded as a DSECT. 

DREC = 

Indicates that the control block for data recording is to be expanded 
for a DSECT. 



GFMB = 

Indicates that the control block for the GETWA/FREEWA main block is 
to be expanded as a DSECT. 
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DUWPLOG 



The DUMPLOG macro is used to dump (unload) logged copies of virtual 
storage resident arrays from the log data set to a sequential data set 
which may then be accessed by user-written routines. 



[symbol] 



DUMPLOG 



NAME= name 
NUMBER= number 



NAMELST= 
NUMBLST= 
, STARTIM= 
,STOPTIM= 
, DUMPDD= 
,USRDATA= 



i address ) 
I (r) / 

( address \ 
\ (r) / 



address 
(r) 

address 
(r) 

address 
(r) 

address 
(r) 

DUMPLOG 
ddname 

d 
( 



}] 
}] 
}] 



address 
r) i\ 



,DCVTR= r 

,DCVTLOC= {^^^^f ^} 
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The parameters NAME, NUMBER, NAMELST, and NOMBLST are mutually 
exclusive. The macro will not expand if more than one of these 
parameters is specified or if all of these parameters are omitted, 

NAME= 

Specifies the name of a named array for which the log array is to be 
dumped. 

NUMBER= 

Specifies the number assigned to a numbered array for which the log 
array is to be dumped. 

NAMELST= 

Specifies the address or a register (2-12) which contains the address 
of a user-constructed list of array names for which the log arrays 
are to be dumped. The name list will be a table of 8-byte entries 
with one valid array name in each entry- The first byte past the last 
valid entry will be set to X'FF» to indicate the end of the name list. 



EXAMPLE: Name List 

0 



ARRAYNAM 



HOUSTONb 



TEXASbbb 



X'FF 



NUMBLST= 

Specifies the address or a register (2-12) which contains the address 

of a user-constructed list of array numbers for which the log array 

are to be dumped. The number list will be a table of half word entries 

with one valid array number in each entry. The first byte past the 

last valid entry will be set to X'FF' to indicate the end of the number 
list. 



EXAMPLE: Number List 

0^ 

2 



H r 



H'255' 



H'I39' 



X'FF 



STARTIM= 
Specifies an address o 
a 6-byte time and day 
first four bytes will 
last two bytes will co 
the day of the year, 
until a copy is found 
start time specified, 
commence with the olde 



r a register (2-12) containing the address of 
field beginning on a fullword boundary. The 
contain a time in 10 millisecond units. The 
ntain a binary value from 1 to 366 representing 
The logged copies of the array will be searched 
with a log time egual to or greater than the 
If this parameter is omitted, dumping will 
St logged copy of the array. 



STOPTIM= 

Specifies an address or a register (2-12) containing the address of 
a 6-byte time and day field beginning on a fullword boundary. The 
first four bytes will contain a time in 10-milli second units. The 
last two bytes will contain a binary value from 1 to 366 representing 
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the day of the year- The logged copies of the array will be dumped 
until the most recently logged copy has been dunped or until a copy 
is dumped with a log time equal to or greater than the stop time 
specified. If this parameter is omitted, dumping will terminate when 
the most recently logged copy of the array has i>een dumped. 

Note: The DUMPLOG routine will insert a byte of X»FF* into the first 

byte of the logging header of the last copy of each array dumped 
to the sequential data set to indicate the end of the dump of 
each array is to be a usei: delog routine, 

DOflPDD= 

Specifies the name of a data definition statement which describes a 
sequential data set to receive the dumped copies of the array from 
the log data set. If this parameter is omitted, the DD name 'DaMPLOG* 
will be assumed as the default. The output will consist of spanned 
variable length records. The blocksize of the data set defined by 
the DDMPDD parameter must be at least 26** bytes but no more than 32760 
bytes. The blocksize should be large enough to contain one array 
copy, the log header (2U bytes), the user dump header (256 bytes) if 
any, and the descriptor words for variable length records (8 bytes) 
for maximum processing efficiency- 

USRDATA= 

Specifies an address or a register (2-12) containing the address of 
a 256-byte area of user data to be contained in the dump header fo-^ 
each array on the sequential dump data set. 

DISP= 

Specifies whether the dumped copies are to be written at the beginning 
of the DOflPDD=data set (DISP=NEW) or added to the existing dumped 
copies (DISP=ADD) - 

If the disposition parameter specified on the DD statement for this 
data set is either OLD or SHE and the data set is empty then the first 
DDMPLOG request must specify DISP=NEW- 

Specifying DISP=llEH on subsequent DOMPLOG requests will position a 
direct access data set to record one and will cause a tape data set 
to force the end of volume before the log copies are written. 

DCVTR= 

Specifies a register (2-12) which contains the address of the XCVT. 
DCVTLOC= 

Specifies the address or a register (2-12) enclosed in parentheses 
which contains the address of a core location which contains the 
address of the XCVT. 

MF=L 

Indicates that the list form of the macro is us6d to create a parameter 
list that can be referenced by an execute form of the DUMPLOG macro 
instruction- 

MF=(E address 

Specifies that the execute form of the DOMPLOG macro instruction and 
an existing parameter list are used. 

Note: A zero returned in register 15 indicates successful coppletion. 

A no n- zero in register 15 indicates that one or more errors were 
encountered during processing of this DUMPLOG request. The 
high-order byte of register 15 contains a count of the number 
of errors encountered and the low-order 3 bytes contain the 
address of the first invalid array name or number. 
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EXIT 



The EXIT macro is to be used in conjunction vith the BEGIN macro and 
will perform the exit linkage convention requirements- That is, 
register 13 will be restored to point to the caller's save area; the 
other general purpose registers that were saved will be restored; and 
the GETHAlNed save area, if one exits, will be released- 

The following options are available for the EXIT macro. 



CODE= 

Specifies a return code to be passed to the RETURN macro; if a register 
is to contain the return code, only 15 is valid. 

FREE= 

Specifies whether or not EXIT is to FREE the save area allocated by 
the corresponding BEGIN macro. Either a FREEMAIN or FREEWA will be 
executed, depending upon how the save area was gotten- 

The following parameters are meaningful only if FREE=YES is specified 
and the save area was allocated by GETWA- 

DCVTR= 

Specifies a register (2-12) which contains the address of the XCVT. 
DCVTLOC= 

Specifies the address or a register (2-12) enclosed in parentheses 
which contains the address of a storage location which contains the 
address of the XCVT. 
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[symbol] 



EXIT 





FREEWA 



The FREEHA macro releases control of a work area obtained via the GETWA 
macro. If the GETHA was not TYPE=PC, the PPEEWA must be issued under 
the same task as the corresponding GETWA. 



where »r' is a general purpose register (2-12) 

If 'r» is specified, the register contains the address of the work area 
as returned to the caller after a GETWA macro execution. 

If an 'address* is specified, it is a label of a fullword that contains 
the address of the work area as returned to the caller after a GETMA 
macro execution. 

DCVTF=r 

Where *r' is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC= (r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses having the address of a 4-byte location that contains 
the address of the XCVT. 

DCVTLOC=address 

Where 'address' is the label of a <4-byte location that contains 
the address of the XCVT. 

When control is returned, register 15 contains one of the following 
return codes: 



[symbol] 



FREEWA 




Decimal 
Code 



Descript ion 



0 



Successful completion. 



Invalid FREEWA; 



Area already free 



Invalid address 



APPLICATION SERVICES 2-205 



GET ARRAY 



The GETARRAY macro is used to retrieve the data contained in one or 
more arrays of the data base, the address of those arrays in the data 
base, or the specifications of the items in the array (s). When data 
is to be retrieved from the data base and the amount of space required 
to contain the data is unknown, the GETARRAY macro with a TyPE=ADDR 
option can be used to obtain the size of the array before the macro 
with a TYPE=DATA or TYPE=SPEC option is used to retrieve the data. The 
macro does not actually return the size of the data area to contain an 
array's item names and specifications but instead will return the number 
of items contained in the array. The number of items can then be 
multiplied by 16 to obtain the actual size of the area for TYPE=SPEC. 
Where incr is specified, it may be any value from 1 to 255. 




NUMBER=nuinber , DATA= / .J^^ I 

( address / 

NAME=name , DATA= (address f 

NAMELST= (< address}- [,incr] 
(r) 



ADDRLST= (| address I 
(r) 



NUMBLST= (< address 



I address I 



, DATALST= ( I 
,FINDLST= (| 



(r) 
address 

(r) > 
address 



, incr] 
, incr] 
, incr] 
, incr] 



{ DATA )" 
ADDR J 
SPEC )_ 



, PROTECT= 



( YES \ 
\ RISK/ 



, DCVTR= r 

,DCVTLOC=( (r) 

(address 
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The parameters NUriBER = , NANE=, NAMELST=, ADDRLST, KUMBLST^ are mutually 
exclusive, only one may be specified. 



NAME= 

Is an 8-character name of a single array for which data is to be 
retrieved or the address is to be resolved, 

NUflBER = 

Is an array number of a single array for which data is to be retrieved 
or the address is to be resolved. 

DATA = 

Is used with NAME= or NUHBER=. It specifies the address into which 
the content of the array is to be moved (TYPE=DATA) or the address, 
number of blocks, length of the array, or size of each block is to be 
moved. In the latter case, the address will occupy a fullword, and 
the number of blocks and the length of each block will occupy the next 
two halfwords, 

NRMELST= 

Specifies the address of a list of 8-character array names for which 
data is to be retrieved or the addresses are to be resolved. Incr is 
the value by which this address is to be incremented to locate the 
next name. If not specified, a value of 8 is assumed« A value or 

less than 9 must not be specified for incr. The list must be 
terminated by a byte containing X'FF* in the position that would be 
occupied by the first byte of the next name. 

NDMBLST= 

Specifies the address of a list of 2~byte fields containing array 
numbers for which data is to be retrieved or the addresses are to be 
resolved. Incr is the value by which this address is to be incremented 
to locate the next number. If incr is omitted, a value of two is 
assumed. A value less than two must not be specified for incr. The 
list must be terminated by a byte containing X'FF' in the first byte 
of the 2-byte field which would be occupied by the next array number. 



EXAMPLE 



Number List 



HT 



H'255' 



H'139' 



X'FF' 



ADDRLST= 

Specifies the address of a list of data base array addresses as 
returned from a previous execution of this macro with NAME=, NAMELST=, 
or NUMBLST= specified and TYPE=ADDE. Incr is the value by which this 
address is to be incremented to locate the next array address. If 
incr is not specified, a value of 8 is assumed. This list must be 
terminated by four bytes containing X'FFFFFFFF' in the position that 
would be occupied by the first four bytes of the address of the next 
array. If the GETAHRAY macro specifying NAMELST or NUMBLST is used 
to build this list, it will place the U X'FF' at the end of the list. 

DATALST= 

Is used with NAMELST= or NUMBLST= and TYPE=DATA or SPEC or ADDRLST= 
and TYPE=DATA. The address of a list of addresses into which the data 
from the specified arrays is to be moved. This must contain an entry 
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for each array for which data is to be retrieved. This entry siill 
contain a fullword address which identifies the memory address to 
which the first byte of the array data is to be moved. Incr is the 
value by which the address within the list is to be incremented to 
pick up the memory address to receive the start of the next array. 

If incr is not coded, a value of H is assumed.; 

FINDLST= 

Is used with NAMELST= or NOMBLST= and TYPE=ADDR. It specifies the 
address of an area to receive an entry for each array specified. This 
entry will be eight bytes if incr is specified as less than 10 (or 
omitted) and 10 bytes if incr is specified as 10 or greater. The 
entry will be in the following format. 



flag 


array 


number 


array /bk 


address 


blocks 


size 



number 
items 



If bit 7 of the flag byte is set to 1, the array is direct access 
resident, and the address is not valid. If flag bit 6 is set to 1 , 
it is a blocked array, and the block size must be multiplied by the 
number of blocks to determine the total size of the array. The number 
of items is the number of item names specified for this array through 
the offline definition of the array. 

Incr is the value by which the address specified is to be incremented 
to determine the location to receive the next entry. If incr is not 
specified, a value of 8 is assumed. 

TYPE= 

Specifies the type of request, DATA specifies that the content of 
the array(s) is to be moved into the area specified by the DATA= or 
DATALST= parameter- ADDR specifies that the address of the array (s) 
and associated data as defined with the FINDLST parameter is to be 
moved into the area specified by DATA= (if NAME= or NUMBEE= is 
specified) or FINDLST= (if NAMELST ov NOMBLST is specified). SPEC 
specifies that the definition specifications as specified to the 
offline utility for each named item defined for the array (s) is to be 
moved into the area specified. 

The data that is returned when the TYPE=SPEC is specified will contain 
a 16-byte entry for each named item in the following format: 



name len 


type 


disp 


1 aid 


rept 


6 ^ 


9 


10 


12 


14 



name The 8-character came of the item, 
len The length of the item in bytes, 

type The data type of this item. An EBCDIC character as defined 
through the ITEM macro. 

disp The displacement into the array (or block) of the item. 

aid The ID of the array as assigned by the offline utility program. 
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rept The number of identical and sequential items defined by this 
entry. 

PROTECT=YES 
RISK 

If YES is specified, a LOCK will be set to prevent other programs that 
also specify PROTECT=YES from accessing the data base via the data 
base macros while the data is being moved. If another program is in 
the process of modifying the data base (a lock is set) when this macro 
is executed, this program will be delayed until the lock is released. 
The parameter has no effect if TYPE=ADDR or TYPE=SPEC is specified. 

DCVTR= 

Specifies a register which contains the address of the XCVT. 
DCVTLOC= 

Specifies the address or a register containing the location which 
contains the address of the XCVT- 

After execution of the GETARR&Y request^, the return code in register 
15 is set to zero to indicate successful completion or to four to 
indicate that the request could not be satisfied because of one or 
more of the following reasons: 

• One or more of the named arrays is not defined to the system. 

• A numbered array was requested which is higher than the highest 
numbered array defined to the system- 

• A TYPE=DATA request was made for a direct access resident array. 
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GETBLOCK 



The GETBLOCK macro will retrieve the data from blocked arrays and place 

that data into user-allocated storage. The macro may be used to 

retrieve one or more blocks of data from one or more arrays. The arrays 
may be either virtual storage or direct access resident. 



symbol] 



GETBLOCK 



NAME= 



name 



NUMBER= 



NAMELST= 



NUMBLST= 



, DATALST= 



(r) 

(number 
(r) 

[address 
(r) 

[address 
(r) 

[address 
(r) 

,PROTECT=|^^|^| 



,DCVTR= r 



l-(,DCVTLOC= 



Iaddr 
(r) 



ess 



|] 



The parameters NA1E, NUMBER, NAMELST, and NUMBLST are mutually 
exclusive. The macro will not expand if more than one of these 
parameters is specified or if all of these parameters are omitted. 

DCVTR= 

Specifies a register (2-12) which contains the address of the XCVT. 
DCVTLOC= 

Specifies the address or a register (2-12) enclosed in parentheses 
which contains the address of a location which contains the 
address of the XCVT. 

NAME= 

Specifies the name or a register (2-12) from which data is to be 
retrieved. 

NUMBER= 

Specifies the number or a register (2-12) from which data is to be 
retrieved. 

NAMELST= 

Specifies the address or a register (2-12) which contains the address 
of a user-constructed list of array names from which data blocks are 
to be retrieved. The name list will be a table of 8-byte entries with 
one valid array name in each entry. The first byte past the last 
valid entry will be set to X'FF' to indicate the end of the name list. 
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EXAMPLE 

0- 

8 



Name List 



ARRAYNAM 



HOUSTONb 



TEXASbbb 



X'FF' 



NUMBLST= 

Specifies the address or a register (2-12) which contains the address 
of a user-constructed list of array numbers from which data blocks 
are to be retrieved. The number list will be a table of halfword 
entries with one valid array number in each entry. The first byte 
past the last entry will be set to X'FF* to indicate the end of the 
number list. 

EXAMPLE: Number List 



HT 



H'255' 



H'I39" 



X'FF 



DATALST= 

Specifies the address or a register (not register 1) which contains 
the address of a user-constr ucte d list of block numbers and of core 
addresses where the data blocks are to be written- The data list will 
be a table of 6-byte entries. Each entry will contain a 1-byte flag 
field, a 3-byte area address and a 2-byte block number. 

PROTECT= 

If YES is specified^ a LOCK will be set to prevent other programs that 
also specify PROTECT=YES from accessing the data base while this 
GETBLOCK is in the process of accessing the data base. If RISK is 
specified, the data will be moved without regard to other programs 
which may be storing into the data base. 

DATA LIST ENTRY DESCRIPTION: 



0 I 2 3 4 5 



FLAG 


AREA ADDRESS 


BLOCK 


BYTE 




NUMBER 



FLAG BYTE 

X'UO' — Indicates the last entry to be processed for a 

particular entry in the name list or number 
list. 

X«ao» or X«80» — Indicates the last entry in the data list- 
AREA ADDRESS 

The 3-byte address of a user-allocated area of storage where the data 
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block is to be written. The area must be large enough to contain the 
entire data block. 



BLOCK NUMBER 

The number assigned to thu data block to be retrieved and placed in 
the area pointed to by the area address. 

EXAMPLE: Data List and Name List 



Name List 



FlRSTbbb 



SECONDbb 



THIRDbbb 



X'FF 





A(Area) 


HT 




A(Area) 


H'5' 


X'40' 


A(Area) 


H'lO' 


X'40' 


A(Area) 


H'3' 




A(Area) 


H'255' 




A(Area) 


H'r 




A(Area) 


H'2' 




A(Area) 


H'sr 




A(Area) 


H'186' 


X'80' 


A(Area) 


H'249' 



Blocks in first 
array 



Blocks in second array 



Blocks in third array 



Note: A zero returned in register 15 indicates successful completion, 
A non-zero returned in register 15 indicates that one or more 
errors were encountered during the processing of this GETBLOCK 
request. The high-order byte of register 15 contains a count 
of the number of errors encountered and the low-order three 
bytes contain the address of the first invalid array name or 
number . 
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GETITEM 



The GETITEM macro is used to retrieve the data contained in one or more 
items of the data base or, alternately, the address or definition 
specification of those items in the data base. When data is to be 
retrieved from the data base and the amount of space required to contain 
the data is unknown, the GETITEM macro with a TYPE=ADDF option can be 
used to obtain the size of the item before the macro with a TYPE=DATA 
option is used to retrieve the data* Where incr is specified, it may 
be any value from 1 to 255. 



[symbol ] 



GETITEM 



NAME= name 
NAMELST= 

ADDRLST^ 



(r) 

( I address I [ ,incr] ) 



i (r) \ 
( i address I [,incr]) 



!data) 1 
ADDR 
SPEC 



number | 



,BLKNO= I 

,DATA= J I , . 

( i. address J [,incr 



] ) 



, PROTECT= 



,DCVTR= r 



, DCVTLOC= 



{ 



YES 1 
RISK J 



i (r) ' 
(address; 



NAME= 

Is an 8-character name of a single item for which data is to be 
retrieved or the address is to be resolved. 



NAMELST= 

Is the address of a list of 8-character ITEM names for which data is 
to be retrieved or the addresses to be resolved. Incr is the value 
by which this address is to be incremented to locate the next name. 
If not specified, a value of 8 is assumed. If specified, must not be 
less than 8. The end of the list must be indicated by a byte 
containing X*FF' in the position that would be occupied by the first 
byte of the next name. 

If the items are contained in blocked arrays and TYPE=DATA or TYPE=ADDR 
is specified, the block number for which data is to be retrieved must 
be specified in the halfword immediately following the 8-byte name. 
Also the BLKNO= parameter should be specified as BLKN0=1, and the incr 
must be coded as a value of least 10, 



TYPE= 

Specifies the type of request. DATA specifies that the content of 
the ITEM (s) is to be returned. ADDR specifies that the address within 
the data base of the item(s) and the length(s) of the item(s) is to 
be returned. DATA and ADDR are invalid for direct access resident 
arrays- SPEC specifies that the definition specifications associated 
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with each item is to be returned. If the ADDRLST parameter is used, 
this parameter must be omitted, or DATA must be specified. 

ADDRLST= 

Is the address of a list of data base item addresses as returned from 
a previous execution of this macro with NAI1E= or NAMELST= specified 
and TYPE=ADDR. Incr is the value by which this address is to be 
incremented to locate the next item address. If incr is not specified, 
a value of 4 is assumed. The end of the list must be indicated by a 
4-byte field containing X'FFFFFFFF' in the position that would be 
occupied by the next address. If the GETITEH macro with NAMELST option 
is used to build this list, it will place the 4 X»FF» at the end of 
the list. 

DATA= 

Is the address into which the first data is to be stored. If TYPE^DATA 
was coded, DATA is the data from the first item specified, according 
to the length defined for the item in the data base. If TYPE=ADDR 
was coded, the length of the ITEM as defined in the data base is moved 
into the byte specified, and the address in the data base of the item 
is moved into the next three bytes. If TYPE=SPEC is coded, the 
specification for each item as defined to the offline utility will be 
returned. This will occupy an 8-byte field for each requested item 
and will have the following format: 



len 


type 


disp 


aid 


rept 


0 


1 


2 


4 


6 



len The length of the item in bytes 

type The data type of this item- An EBCDIC character as specified 
in the ITEM macro to the offline utility 

disp The displacement into the array (or block) of this item 

aid The ID of the array in which this item resides as assigned by 
the offline utility 

rept The number of identical and sequential items defined by this 
entry. 

Incr is the value by which the data address is to be incremented to 
determine the next address to move either the next address or data. 
If incr is not coded and TYPE=DATA, the length of the moved item will 
be used as the increment. If incr is not coded and TYPE=ADDR or 
TYPE=SPEC, a value of 4 is assumed. If incr is coded and TYPE=DATA, 
the data will be moved for the defined length of the item, up to the 
number of bytes defined by the incr value. If TYPE=ADDH or TYPE=SPEC 
is coded, four bytes of data will be moved in any case, and if the 
incr value is less than the movement of data may overlay previously 
moved data. 

When TYPE=ADDR is coded, a terminator flag (X'FFFFFFFF') will be moved 
into the position that would be occupied by the next address after 
the last to be resolved. 

PROTECT=YES 
RISK 

If YES is specified, a LOCK will be set to prevent other programs that 
also specify PROTECT=YES from accessing the data base via the data 
base macros while the GETITEM is in the process of accessing the data 
base (a lock is set) . when this macro is executed, the other program 
will be delayed until the lock is released. If RISK is specified. 
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the data will be moved without regard to other programs »hich may be 
storing into the data base. 



BLKNO= 



0 

number 



If U is specified or if the parameter is omittedg, the array is assumed 
to be unblocked, 

A number is used to specify that the data is to be retrieved from a 
blocked array(s) . If NAME= was specified^ the number is the block 
number from which data is to be retrieved- If NAI!ELST= is specified, 
any number from 1 to 32765 may be coded to indicate that the block 
numbers are coded as part of the NAfiELST, 

DCVTR=r 

Where 'r' is the general purpose register ([2-12) that contains the 
address of the XC7T- 

DCVTLOC=(r) 

Where »r' is the general purpose register (2-12) enclosed in 
parentheses that has the address of a 4- byte 3ocation that 
contains the address of the XCVT. 

DCVTLOC=address 

Where 'address* is the label of a 4-byte location that contains 
the address of the XCVT. 

When control is returned register 15 contains one of the following 
return codes: 



Decimal 
Code 



Descript io n 



0 



Successful execution. 



One or more of the item names specified could not be 
resolved or data was requested to be moved for an item 
with a defined length of 0 bytes« 



8 



Invalid options were passed to the GETITEM routine 
(probably the macro expansion had been modified) . 



12 



A block number was specified for an unblocked array or 
a block number was specified that is greater than the 
highest block number defined for the array. 



16 



GETITEM request for an item that is contained in a direct 
access array. 
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GETLOG 



The GETLOG macro retrieves logged arrays by time or by using array 
logging header information. 



[symbol] 



GETLOG 



NAME= { "J^f } 



NUMBERS {"'J^^'^} 



,STEP= < value 



,TIME= I 



(r) ) 

address I 

(r) : 



|^,PROTECT= {^} ] 

,DCVTR= r \ 
,DCVTLOC= l^^^^f ^ } 

[,MF=L] [.MF=(E, 
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The parameters NAME and NUMBER are mutuially exclusive. The macro will 
not expand if more than one of these parameters is specified or if both 
of these parameters are omitted. 

NRME= 

Specifies the name or a register (2-12) containing the address of the 
name of a named array for which a logged copy of the array is to be 
retrieved. 

NUMBER= 

Specifies the number or a register (2-12) containing the number of a 
numbered array for vfhich a logged copy of the array is to be retrieved. 

AREA= 

Specifies an address or a register (2-12) containing the address of 
a user-allocated storage area where the logged copy of the array will 
be written upon retrieval from the log data set. This area must be 
large enough to hold the entire array and logheader (21 bytes). AREA 
is a reguired parameter. 

STEP= 

Is used to determine which copy of a logged array, relative to the 
TIME or LOGHDR parameters^ Kill be retrieved from the log data set. 
The value is a signed number which may be either positive, negative, 
or zero. If the STEP parameter is omitted, a value of zero will be 
assumed as the default. If no sign is specified, the number is assumed 
to be positive. 

PROTECT= 

If YES is specified, a LOCK will be set to prevent other programs that 
specify PROTECT=YES from accessing the data base while this GETLOG is 
in the process of accessing the data base. If RISK is specified, the 
data will be moved without regard to other programs which may be 
storing into the data base, 

(See GETLOG examples on the following pages for use of this parameter 
in combination with the TIME and LOGHDR parameters.) 

TIME== 

Specifies an address or a register (2-12) containing the address of 
a 6-byte time and day field beginning on a fullaord boundary. The 
first four bytes will contain a time in 10 millisecond units. The 
last two bytes will contain a binary value from 1 to 366 representing 
the day of the year. This time and day will be used as a comparison 
value to establish a relative starting point to determine which copy 
of the array will be retrieved from the log data set- The TIKE 
parameter cannot be specified if the LOGHDR parameter is specified. 

LOGHDR= 

Specifies an address or a register (2-12) containing the address of 
an array logging header. Information in this logging header will 
establish a relative starting point to determine which copy of the 
array will be retrieved from the log data set. The LOGHDR parameter 
cannot be specified if the TIME parameter is specified. 

The logging header is a 2't-byte control block which precedes the array, 
both as the array exists in VS and as it is written to the logging 
array. The logging header which was retrieved as part of a previous 
GETLOG macro can be used to retrieve additional data stepping either 
forward or backward in time. 

DCVTR= 

Specifies a register (2-12) which contains the address of the XCVT. 
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DCVTLOC= 

Specifies the address or a register (2-12) enclosed in parentheses 
which contains the address of a location which contains the 
address of the XC7T. 

nF=L 

Indicates that the list form of the macro is used to create a parameter 
list that can be referenced by an execute form of the GETLOG macro 
instruction. 

MF=(E, address ) 
(r) 

Specifies that the execute form of the GETLOG macro instruction and 
an existing parameter list are used. 

When control is returned, register 15 contains one of the following 
return codes; 

Decimal 

Code Description 

0 Successful completion- 

U Requested time is later than most recent logged copy. 

The most recently logged copy sill be read into the user 
defined area. 

8 Invalid STEP parameter value- 

The number of log copies -1 will be substituted for the 
STEP parameter and that logged copy will be read into 
the user defined area- 

16 The specified array had not been defined. No data is 

read into the user defined area. 

20 The specified array is not a loggable array. No data 

is read into the user defined area. 



GETLOG Examples 

These examples will not describe the Assembler Language statement used 
to call the GETLOG macro, but will describe the response of the GETLOG 
routine to the different combinations of the TIME and L03HDR parameters 
with the STEP parameter. 

• STEP, TIME, and LOGHDR omitted — Information will be extracted 
from the logging header on the virtual storage resident copy of 
the array, and the last logged copy of the array will be retrieved. 

• TIME is specified and STEP= 0 or omitted — An attempt will be made 
to retrieve a copy of the array logged at the exact time specified. 
If the array was not logged at that exact time, the first copy of 
the array logged after that time will be retrieved. 

• TIME is specified and STEP=-2 — The second copy of the array logged 
prior to the time specified will be retrieved. 

• TIME is specified and STEP=-f5 — The fifth copy of the array logged 
after the time specified will be retrieved- 

• LOGHDR is specified and STEP=0 or omitted — Information will be 
extracted from the logging header specified and the copy represented 
by the logging header specified will be retrieved. 
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LOGHDR is specified and STEP=-3 Information will be extracted 
from the logging header specified and the third copy prior to the 
copy represented by the logging header specified will be retrieved, 

LOGHDR is specified and STEP=+4 Information will be extracted 
from the logging header specified, and the fourth copy after the 
copy represented by the logging header specified will be retrieved. 
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GETWA 



The GETWA macro provides the facility for obtaining, short-term work 
areas without adversely increasing paging rates. The work areas can 
be freed explicitly with the FREEWA macro or freed automatically at 
the end of the current patch queue or at the end of the current task 
processing. The address of the work area is returned in register 1. 
If the GETRA was unsuccessful, register 1 will contain 32 binary ones. 



where 'r' is a general purpose register, 2-12. 



length 

Is the length of the requested work area that can be specified in any 
BX-type format or in a general purpose register. 

TYPE= 

Specifies the status of the work areaj If omitted or if TYPE=AP is 
specified, the work area will be freed automatically when the 
processing of the current PATCH work queue element is completed. If 
TYPE=AT is specified, the work area is freed when the current task 
terminates. If TYPE=PC is specified and the work area is completely 
under program control, a FREEWA must be specified for the work area. 
A FREEWA may be specified for any type of GETWA. GETWA TYPE=AT 
executing under a QP or GETWA areas passed via PATCH to the AT chain 
of a QP will ne/er be freed by Special Real Time Operating System (a 
QP can never be DPATCHed) . 

DCVTR=r 

Where 'r' is ths general purpose register (2-12) that contains the 
address of XCVT. 

DCVTLOC= (r) 

Where 'r* is th-3 general purpose register (2-12) enclosed in 
parentheses, ha/ing the address of a 4-byte location that contains 
the address of XCVT. 

DCVTLOC= address 

Where 'address' is the label of a U-byte location that contains 
the address of the XCVT. 

GETWA SETaEN CODES: 



[symbol] 



GETWA 




,DCVTR= 



r 




Decimal 
Code 



Descriptio n 



0 



Successful completion. 



Invalid size requested. 



12 



An attempt was made to obtain additional GETWA storage. 
The attempt was unsuccessful because there was 
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insufficient CBGET storage to build the GETWA control 
blocks. 
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LOCK 



Every resource that has been previously defined by a DEFLOCK macro can 
be exclusively reserved by use of a LOCK macro. The address of the 
control block (which is returned by the DEFLOCK macro) must be specified 
in the LOCK macro. If the resource is unavailable at the time, the 
LOCK macro is issued, and the requesting task is placed in a wait state 
until that resource becomes available. Another LOCK macro must be used 
to release the resource. 

Note: The LOCK macro used to release the resource must be executed 
from the same task as the LOCK macro used to reserve the 
resource. 

If a Special Real Time Operating System task (i.e., a PATCHed task) 
terminates or ABENDS before releasing the resource, the Special Real 
Time Operating System exit routine will release the resource for that 
task. However, if a non-Special Real Time Operating System task (i.e., 
an ATTACHed task) returns or ABENDS before releasing the resource, the 
LOCK will remain set indefinitely. 

The following operands are available for the LOCK macro: 



[symbol] 



LOCK 



( name ; 
,CBLOC= 
,TYPE= 



( (r) ) 
( address) 

/ LOCK ) 
\ UNLOCK / 



1= r 



, DCVTR= 
,DCVTLOC= I 



(r) 
address 



(r) 

name 

The positional operand defines the 4-byte resource name. If (r) is 
specified, the general purpose register must contain the resource 
name. 

CBLOC= 

The CBLOC= keyword parameter is used to indicate the address of the 
control block as defined by the DEFLOCK macro. If (r) is specified, 
general purpose register 1 should contain the control block address. 
"Address" is the label of a fullword that contains the control block 
address, 

TYPE= 

Is used to indicate that a resource is being reserved (TYPE=LOCK) or 
released (TYPE=UNLOCK) . 

DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XCVT. 



DCVTLOC=(r) 

Where "r* is the general purpose register (2-12) enclosed in 
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parentheses that has the address of a U-byte location that 
contains the address of the XCVT. 

DC VTLOC= address 

Where 'address* is the label of a 1-byte location that contains 
the address of the XCVT. 

When control is returned, register 15 contains one of the following 
return codes: 



Decimal 
Code 



De sc ri ptio n 



0 



Successful completion. 



4 



This task has 
the resource 



previously reserved and has control of 
(TYPE=LOCK) , 



8 



This task has 
(TYPE=UNLOCK) 



not previously reserved the resource 



16 



Invalid resource name and control block address 
combination. Resource will not be reserved. 
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MESSAGE 



The MESSAGE macro is used by the Special Real Time Operating System 
and the programs running under the Special Real Time Operating System 
are used to cause a predefined message to be printed or displayed. The 
message must have been defined through the offline utility system using 
the DEPMSG macro. 



[symbol] 



MESSAGE 



(r) 
nuniber 



,ACT. j i ) 
j^,ROUTE= (| 



(r) 
CI 



,VAR= 



,AREA= 



(r) 
addressl 



(r) 
iaddress2 



j (r) 
) address] 



/ addre 



s^L.!][.""-|i5l] 



olio 



, DCVTR= r 



,DCVTLOC= I ( 
J address! 



symbol 

Is any symbol valid in the assembler language, 
number 

Is a unique 3-digit number which identifies the requested message, 
(r) is the general purpose register (2-12) enclosed in parentheses 
which contains the message number. 



ACT= 

Is the action code to be appended to the message number. I denotes 
information. A denotes action is required, and D denotes that a 
decision is required. If not coded, the action code specified through 
the offline utility will be used. 

ROUTE= 

Is the code or codes that identify the devices on which this message 
is to be displayed or printed. Dnique routing codes are associated 
with def'ices during the Special Real Time Operating System build 
procedure. If this parameter is not included, the message will be 
routed to the devices specified through the offline utility procedure 
using the DEFMSG macro. The maximum number of routing codes that can 
be specified is 8. (r) is the general purpose register (2-12) enclosed 
in parentheses which contains the route code. 

VAR= 

Is variable data to be converted and inserted into the message to be 
output. The variables must be in the sequence and lengths specified 
through the offline definition of the messages The maximum number of 
variables that can be specified is 10, addr is any address valid in 
an RX-type instruction, and (r) is a general purpose register (2-12) 
which contains the address. 



WAIT= 

Informs the Special Real Time Operating System that performance of 
the active task cannot continue until the specified message has been 
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issued. YES specifies that the active task is to go into a wait state; 
and NO specifies that the active task is not to wait until the 
specified message has been issued. 

AHEA= 

Is the address into vhich the formatted message is to be returned to 
the caller. The term addr is any address valid in an RX-type 
instruction and (r) is any register that was loaded with the address. 

DCVTR=r 

Where *r» is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC=(r) 

Where (r) is the general purpose register (2-12) enclosed in 
parentheses that has the address of a 4-byte location that 
contains the address of the XCVT. 

DCVTLOC=address 

Where 'address' is the label of a a-byte location that contains 
the address of the XCVT, 

MESSAGE RETURN CODES: 

The Message Handler will issue return codes through register 15, If 
the return code is 08 or greater, the message is not output. 



Decimal 
Code 



Description 



0 



Normal completion. 



2 



Specified number of variables less than number of 
variables specified through offline utility procedure. 
The remaining varieibles are padded with hyphens. 



Specified number of variables greater than number of 
variables specified through offline utility procudure. 
The last variables in the list are dropped until number 
of specified variables equals number of variables defined 
through offline utility procedure. 



8 



Invalid message number. 



12 



Invalid routing code. 



16 



Input/output error. 
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— List Form 



The list form of the MESSAGE oacro is used to construct a problem 
program parameter list- This problem program parameter list can be 
referred to in the execute form of a MESSAGE macro instruction. 



The descripti 
provides the 
description o 
totally optio 
list and exec 
optional and 
have been def 
m.icro. The m 
rtistrictions 



on of the standard form of the MESSAGE macro instruction 
explanation of the function of each operand. The 
f the standard form also indicates which operands are 
nal and which are required in at least one of the pair of 
ute forms. The format description below indicates the 
required operands in the list form only. The message must 
ined through the offline utility system using the DEFMSG 
essage text will be truncated to conform to the length 
of the device(s) it will be routed to. 



symbol] 



MESSAGE 



number 



I 



,ACT= ^Anl/ROUTE= (CI, [C2, . . . ,C8] ) 



|^,VAR= (addrl , [addr2 ,addrlO] j 

{ws} j 



,MF=L 



, WAIT= 



symbol 

Is any symbol valid in the Assembler Language, 
addr 

Is any address that may be written in an A-type address constant. 
EOUTE= 

The MESSAGE macro will expand space for eight route codes if none are 
specified. 

MF=L 

Indicates the list form of the MESSAGE macro instructioni 
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MESSAGE MACRO — Execute Form 



A remote control program parameter list is used in, and can be modified 
by, the execute form of the MESSAGE macro ins :ructioa. The control 
program parameter list is generated by the list form of the MESSAGE 
macro instruction. 



The description of the standard form of the 
provides the explanation of the function of 
description of the standard form also indie 
totally optional and which are required in 
list and execution forms. The format descr 
optional and required operands in the execu 
must have been defined through the offline 
macro. The message text will be truncated 
restrictions of the device(s) to which it w 



MESSAGE macro instruction 

each operand. The 
ates which operands are 
at least one of the pair of 
iption below indicates the 
te form only. The message 
utility system using DEFMSG 
to conform to the length 
ill be routed. 



[symbol ] 



MESSAGE 



, ROUTE: 



(number/ ,ACT= < 

( (r) \ U (r) ) 
[,VAR= Claddressif ,[(address2/ ,. 

[_,AREA= \addrj j 

[,MF= E, I remote list address! 
I (r) i J 

r,WAIT= ) N0 \ II j ,DCVTR= r 
[_ (yES'/Jl I ,DCVTL0C= / (r) H 

(addressf 



} 



(r) 

addresslOf 



symbol 

Is any symbol valid in the Assembler Language, 
addr 

Is any address that can be written in an A-type address constant- 

HF=(E, remote list address) 
Indicates the execute form of the MESSAGE macro instruction using a 
remote parameter list. The address of the remote parameter list can 
be loaded into register ^, in which case HF=CE,(1)) should be coded. 

ROUTE= 

Cf more route codes are expanded in the remote list than are required 
xn the MF=E form, only the number specified on the MF=E form will be 
modified. For example, if the remote list expanded 5 route codes and 
the MF=E only 2, only the first 2 in the remote list would be modified 
end the message would be routed to all 5 route codes. If this is not 
cesired, the remote list should be zeroed prior to executing the MF=E 
torm. 
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PATCH 



The PATCH macro is used to create a Special Real Time Operating System 
task and to queue work to it. If no task name is specified, a dependent 
task will be created. A dependent task can accept only one PATCH and 
flags are set which will cause it to disappear as soon as the work 
represented by the single queue element is completed. If a name is 
specified, the PATCH SVC checks to determine if an independent task by 
that name already exists, and if not, an independent task is created. 
Then the work is queued to that task. Independent tasks will be kept 
available until they are removed from the system explicitly via the 
DPATCH macro; if all queued work is completed, they will go into a 
dormant state, ready to accept more work with function^ the next PATCH. 

The PATCH macro has two different kinds of operands: task-oriented 
and work-oriented. 

Task-oriented operands are used only at task creation and, if the task 
already exists, they are ignored (priority, queue length, target 
partition) . 

Work-oriented operands are relevant with every execution of the PATCH 
macro (entry point name, queue position, ECB address, FREE request) . 

The various operands available can be used to control overall system 
overhead, core usage, task synchronization, and execution times. Their 
use should be considered carefully so that they correspond to the 
requirements of the task they affect. 

Each time a program is called or executed as a result of a PATCH, a 
parameter list is passed to the program. These parameters may be used 
to identify the PATCHing program, the reason for the PATCH, to pass 
data or an address of data arrays, or, in general, to provide the 
PATCHed program any information it might need to execute a given This 
parameter list is always headed by one word containing the length of 
the parameter area and the ID of the PATCH. The remainder of the 

list can be any combination of values and/or addresses needed by the 
PATCHed program. 

When the PATCH SVC returns to the caller, register 15 will contain a 
return code. In addition, if the return code is less than or equal to 
8 and was for an independent task, register 1 will contain the address 
of the TCB extension (TCBX) , If this address is supplied with the next 
PATCH to the same task (TCBX=) , it will speed up execution of the PATCH 
SVC routine. 

When the "called" program gains control as the result of a PATCH, 
register 1 will contain the address of a 3-word block which contains 
the address of: (a) XCVT, (b) resource table, (c) the parameters 
specified in the PATCH macro. The address of XCVT will be used as 
input to many Special Real Time Operating System macros as the keyword 
operand DCVTR or DCVTLOC. The resource table is a doubleword which is 
allocated and set to zero when the task is created and is maintained 
as a task resource as long as the task is in existence. The user may 
store data into the resource table and have the data preserved between 
independent task (program) executions eventhough the program may be 
deleted or a differeat program may be executed under the same task. 
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PATCH Input Parameter Format 



Rl 



XCVT 



RESOURCE 
TABLE 



PARAMETERS 



Parameters 
as specified 
in PARAM 



1 — g 


LENGTH j 00 


ID 


{ 





> LENGTH 



[symbol] 



PATCH 



TASK = name 



TASKLOC = l^^ll,,] 



EP = (name [ , DELETE] ) 
EPLOC = (address [, DELETE] ) 



,QL = 



,QPOS 



PRTY = 



(r) 
number 



FIRST 
LAST 

BPatch 



( taskname , j j ) 

^ ' (value)'' 

PRTYLOC =({^airLsj'^^l"«) 

'^^^ =(!adirLs! f'REPATCH]) 

IHap n (r) 



,FREE =jV(len) I, address 
' P 



,TCBX = 



PTN = 



,SUPL = 



I (r) 
I address 



OWN 



Master 

SLAVE 
FIND 



(E, I address I ) 
(r) 



,ID = [ l] 

( value ) J 

-(^r. ['p:;::::'p;"'])] 



, PARAM 



,PROBL=^^^ j address j) 



,DCVTR = r 



, DCVTLOC 



( (r) 



( address 

Where 'r' is a general purpose register, 2-12. 
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TASK=name 

Specifies a 1 to 8 character name which is the name of the task or 

queue holder being referenced by this PATCH. If the task does not 

exist, one by that name will be created, 

TASKLOC=address 

Specifies the address of a 1 to 8 character task name. The name must 
be on a full word boundary, be left- justified and padded on the right 
with blanks, if necessary, to complete eight characters. The address 
can be any format valid with an EX-type instruction. 

EP= 

Specifies a 1 to 8 character valid program name which is the name of 
the program to be scheduled under the task being created with the 
PATCH. If DELETE is specified and this is the only task using the 
program, a DELETE is issued for the EP name after processing for this 
PATCH completes. DELETE may be abbreviated as DEL. If EP is not 
specified and an ID other than 2 55 is specified, the PATCH will fail 
during an attempt to LOAD a program with a name of blanks. 

EPLOC=address 

Specifies the address of a 1 to 8 byte program name. The program name 
must begin on a fullword boundary, be left- justified and padded on 
the right with blanks, if necessary, to complete eight characters. 
The address can be in any format valid with an RX-type instruction, 
DELETE has the same meaning as with EP=, 

QL= 

Specifies the limit number of HQEs that may be queued to the 
independent task in addition to the one that might be currently 
executing. This parameter is meaningful only for new, independent 
tasks and is ignored otherwise. Any decimal value from 0 to 255 may 
be specified; the default value is 1 . If (r) is specified, the value 
is assumed to be in the low-order byte of register r. 

If zero is specified as the queue length, the task accepts one PATCH, 
works on it and, when completed, waits for the next request. If a 
PATCH is issued for that task while the task is busy, it is not 
executed. 

If the queue length is 1 , the task can accept one PATCH even while it 
is busy. 

When a task completes processing the current request, the top element 
on the queue will be executed next. 

QFOS= 

S oecif ies where in the task work queue this work request is to go if 
tie task is currently busy, FIRST indicates that it is to be placed 
SD as to be processed before those already in the queue. LAST 
indicates that those already in the queue should be processed before 
this request. If DPATCH is specified, the processing for this PATCH 
Will not be executed until a DPATCH is issued for this task. Only 
oi e PATCH with QPOS=DPATCH is allowed to each task. QPOS=D?ATCH is 
n< t allowed if TASK= specifies a queue holder, 

PR1 Y= 

Specifies a task name and a value which will determine the priority 
of the new task. The value (0-2 55) will be subtracted from the 
dispatching priority of the specified task. If (r) is specified, the 
value is assumed to be in the low-order byte of register r. If a 
value is omitted, zero is assumed. 
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PRTYLOC= 

Has the same function as PRTY except that the task name is an 8-byte 
field at the address specified. The name must be left- justified and 
padded on the right with blanks. The value is specified exactly as 
with the PRTY=operand. 

ID= 

Specifies a decimal valu<* from 0-254 to be passed as a parameter to 
the PATCHed task's program. If (r) is specified, the ID value should 
be in the low-order byte of the register. An ID of 255 is special. 
A PATCH request with an ID of 255 will cause a task to be created and 
initialized if it does not already exist and the module to be loaded. 
It will work its way to the top of the queue, but the program will 
never be entered. This provides a task pre- initialization capability. 
If ID is omitted, a default value of 0 is assumed. If the ID is 255 
and EP is not specified, the task will be created and no program will 
be loaded- 

PARAM= 

Specifies one or more parameters which will be passed to the PATCHed 
task's program. The parameters may be any values or addresses 
meaningful to the program. If { r) is specified for a parameter, the 
value must be contained in the register r; otherwise, the parameter 
expands as an A- type address constant. Note that if only one parameter 
is specified and it is in a register, two sets of parentheses are 
required. 

ECB = 

Specifies the address of an ECB which may be used in a WAIT macro. 
This ECB is posted when processing for this PATCH completes or when 
1 he work represented by the PATCH is purged. The REPATCH option causes 
1 he ECB to be posted with the address of the REPATCH list (REPL) to 
be used in the REPATCH macro if this PATCH is not serviced because of 
a QP0S=FIR5T PATCH with the queue being full. If REPATCH option is 
specified and the REPATCH occurs (ECB posted with a completion code 
of X'^iU'), a REPATCH macro must be issued. See description of the 
REPATCH macro. Note that if only ECB address is specified and it is 
in a register, two sets of parentheses are required. 

FREE= 

Specifies that a work space is to be passed to the PATCHed task and 
is to be freed after the work queue element built in response to this 
PATCH is completed (either GETHAINed area or GETBA area) or after the 
PATCHed task has terminated (GETHA storage ereas only). The area must 
have been obtained via a GETMAIH from subpool zero or a GETWA and must 
be part of the partition where the work reps esented by this PATCH is 
to be executed. If REPATCH option is speci: ied and the ECB is posted, 
the area will not be freed immediately. However, the area will be 
freed as a result of the mandatory REPATCH macro. It is invalid to 
code this operand if the PATCH goes to the other partition and the 
BEPATCH option is specified. 

A work area originally obtained via a GETHAIN macro call may be freed 
by specifying either the length and address of the work area or FREE=P. 
If FREE=P is specified, the problem program parameters (ID and PARAM 
or PROBL=) are FREEMAINed. A GETHAINed ar aa will be FREEMAINed after 
the execution of the work represented by this PATCH. 

A work area originally obtained via a GETWA macro call may br freed 
by specifying either AP or AT and the address of the work area. An 
AP request will cause the storage to be FREEWAed after the execution 
of the work represented by this PATCH. An AT request will cause the 
storage to be freed whenever the PATCHed task is terminated. 
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Any storage area associat id worJc queue built in response to a 
successful PATCH (return code less than eight) and later removed from 
the PATCHed tasks* work queue chain before it can be executed, will 
be freed when the work queue is purged. 

Any format valid for an EX-type instruction can be specified for the 
length or address. 

TCBX= 

Specifies the address of the TCB Extension Control Block (TCBX) for 
an existing independent task. If TCBX is specified as a register, 
TCBX=(r) , that register is assumed to contain the actual TCBX address. 
If TCBX is specified as a relocatable expression, TXCB=addr, the TCBX 
address will be loaded from the specified address. The TCBX address 
is returned in register 1 after each successful PATCH to an independent 
task. Use of this operand with all PATCHes to the same task after 
the initial PATCH will reduce system processing time. Note that other 
parameters must still be specified for verification or in the event 
the task has been DPATCHed. 

PTN= 

In two-partition operation, this operand defines the target partition 
for the PATCH. OWN means that the target partition is the partition 
that executes the PATCH; MASTER defines the MASTER defines the master 
partition as the target partition. SLAVE defines the slave partition 
as the target partition; if SLAVE is coded and two-partition operation 
is not initialized (no MASTER/SLAVE control cards in the SYSINIT input 
stream), the PATTH will be rejected, and a return code is passed back 
in register 15- FIND causes the SVC to search fcr the specified task 
in the patchor's own partition; if it is found, it is used and the 
search exits. If it is not found, a switch is made to the other 
partition which is searched also. If a task by the specified name is 
not foand in e it tier partition, the SVC routine switches back to the 
patchcr's own pcEtition and behaves as if OWN was coded. 

If the PTN operand is not coded, it defaults to OWN. 

If two-position operation is not specified at the Special Real Time 
Operating System SYSGEN, this parameter is ignored. 

SOPL= 

Specifies a list or execute form of the PATCH supervisor operands. 
If the list form, saPL=L is specified, no executable code is generated; 
therefore, all register notations are ignored as well as TASKLOC, 
EPLOC and PRTYLOC. With the execute form, SUPL= (E ,addr) , the address 
specifies a SUPL=L form parameter list, and any additional operands 
specified cause executable code to be generated which modifies the 
remote parameter list before the SVC instruction is generated. The 
address can be in any format valid with an RX-type instruction. SUPL=L 
and PROBL=L cannot both be specified. 

PROBL= 

Specifies a list or execute form of the problem parameter operands, 
ID and PARAM. PROBL=L generates a parameter list, and PROBL= (E,address) 
specifies the address of such a list in an execute form of the PATCH 
macro. Both PROBL=L and SUPL=L cannot be specified. Note: If the 
length of the Note: If the length of th PROBL parameter is equal to 
or less than eight bytes, the entire parameter is moved into a 
supervisor area. This will allow the use of a single PROBL list even 
though the ID might vary with each individual PATCH execution. 

DCVTR=r 

Where 'r* is the general purpose register (2-12) that contains the 
address of the XCVT. 
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DCVTLOC=(r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses having the address of a 4-byte location that contains 
the address of the XCVT. 

DCVTLOC=address 

Where »address» is the label of a 4-byte location that contains 
the address of the XCVT. 

When control is returned, register 15 contains one of the following 
return codes: 

Decimal PATCH 

Cod e Exec uted De sc ript ion 

2 YES TCBX=Address specifies the address of a TCBX 

which does not have the same name as specified 
in the SUPL. The proper TCBX is found or a nev 
task is created.. 

4 YES QPOS=FIRST caused loss of previous WQ, 

6 NO Specified task is in the no-PATCH state* 

8 NO Queue full, 

10 NO PRTY task name does not exist. 

12 NO Invalid PROBL parm list or address. 

14 NO Invalid SdPL parro list or address. 

16 NO DPATCH queue overflow. 

18 NO Invalid FR EE=operand. 

20 NO DPATCH in progress for this task, 

22 NO PTN=SLAVE requested but not initialized. 

28 NO NO CBGET storage for TCBX, WQE or LCB, 

30 NO Task name specified is a queue processor- 

32 NO Task name specified is a queue processor and 

QPOS=DPATCH. 

ECB COMPLETION CODES: 
High-Order Low-Order 

Byt e Code 3- Byte Cod e Descriptio n 

X'UC Same as register successful completion, 

contents from program 

X»42« Zero DPATCH occurred before work could 

be executed, 

X'UU' Address of block REPATCH A PATCH with QPOS=FIRST 

or zero forced this PATCH out of queue. 

X«48» Zero BLDL failed (member not found or 

I/O error) , 
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X»4C« ABEND code Task abnormally terminated while 

processing this request. 

X»4F' Same as The PATCH parameters were specified 

register 15 as part of a PTIME macro. The PTIME 

specification has been deleted, and 
no more PATCHes will be executed. 
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Relationship of Patch Operands to type of Task 



Operands 
or 

Suboperand 


Create 
Independent 
Task 


Queue 
Independent 
Task 


Dependent 
Task 


Program 
Input 
Parameters 


TASK/ 
TASKLOC 


R 


R 


I 




EP/ 
EPLOC 


R 


R 


R 




DELETE* 


O 


O 






PRTY/ 
PR 1 YLOC 


0 


N 


O 




QL 


0 


N 


N 




OPos 


O 


O 


0 




DPATCH* 


0 


O 


O 




ECU 


O 


o 


o 




RLl'ATCH* 


O 


o 


o 




rR[;E 


O 


o 


o 




p* 


O 


o 


o 




n BX 

H) 

P ARAM 




o 




o 
o 



R = Required *Sub<)perand of Preceding Operand 

0 = Optional 
N = Ignored 

1 = Invalid 



Figure 2-34. 
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PTIME 



The PTIME macro provides Special Real Time Operating System time 
management services to the user. The macro causes a task to be PATCHed 
at a specified or relative time. Optionally, this PATCH can be repeated 
at a specified cycle interval continuously or for a certain number of 
PATCHes. The PTIME macro also allows previous PTIME calls to be 
modified or deleted. An additional function of the PTIME macro allows 
access to the correct Special Real Time Operating System time and date. 

The following operands are available for the PTIME macro. 



[symbol] 



PTIME 



ADD 
MOD 
DEL 
RET 



i REL ) |,A=address 
TOD {, (r) 
ADj) {, nH ,nM ,n .n S 



i,STOP= (same format as START) 



/,COUNT= ( 



, INTRVAL= 



[ NO 
I " 

,PURGE= C 
( W 



A=address 
(r) 

nH ,nM ,n .n S 



I (r) /J 



,MF= 



(E, ) (r) 

address 



, DCVTR= r 



,DCVTLOC= 



( address 



j (r) 

[PATCH operands (See PATCH Macro)] 



wi ere 'r' is a general purpose register 2-12. 
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All tine values are specified in the same fornat. The tine is specified 
eiplicitly by hours, ninutes, seconds, or any combination of the three 
as long as one is specified. The time value must not exceed 24 hours. 

Examples are as follons: 

3 hours: 3H or 180B or 10800S 

1 hour, 3 minutes, 1-1/2 seconds: 1H, 3!!, 1.5S or 3781. 5S. 

If (r) is specified, the time in hundredths of seconds is in register 
r. The k= suboperand allows the time value to be specified in a 
fullword at the address specified. The time value in the word must be 
specified in hundredth of seconds. The address may be any RX-type 
address. 

ADD 
HOD 
DEL 

Specifies the type of PTIMB service requested. If omitted or if ADD 
is specified, a PTIBE queue element (PTQE) is activated which controls 
the. PATCHes issued according to the PTIME request. Since the PTQE 
exists independently of the creating tasic and may be modified or 
deleted, the PTQE is referred to by the task name, entry point name, 
and ID value of the parameters referred to by the operands TASK=, 
TASKLOC=, EP=, EPLOC=, and ID= as defined in the PATCH macro. Either 
task name or entry point name must be specified with a modify (HOD) 
or delete (DEL) , but the remaining two are optional. However, if only 
a task name or entry point name is specified, all PTQEs with that name 
are deleted or modified regardless of entry point names or ID values. 

RET 

Causes the system to return the current time in 10 millisecond units 
in register 0 and the address of the Special Heal Time Operating System 
time array in register 1. This time is a Special Real Time Operating 
System time which can be synchronized with an external time source. 
The time and date are maintained in several formats and are updated 
periodically. Thus one PTIME RET call gives a routine the current 
time as long as the address of the array is retained. See the TIMED 
DSECT for a description of time formats. All other operands are 
ignored with RET- 

START= 

Specifies the time of the first PATCH to be executed. The first 
suboperand determines the meaning of the time value specified in the 
remainder of the operand. If REL is specified, or if the operand is 
omitted, the time of the first PATCH equals the current Special Real 
Time Operating System time plus the time value in the remainder of 
the operand. If TOD is specified, the first PATCH occurs when the 
Special Real Time Operating System time equals the time of day 
specified by the remainder of the operand. If this time is less than 
the current Special Real Time Operating System time, the first PATCH 
does not occur until the next day. If ADJ is specified, the time of 
the first PATCH is calculated by assuming the time value in the operand 
to be a TOD value, except that the time value in the INTERVAL= operand 
is repeatedly added to the assumed TOD or ADJ is specified and the 
calculated STOPTIBE is less than the calculated START time until that 
value is greater than current Special Real Time Operating System time. 
This presents the possibility of unintentionally specifying a TOD less 
than th<i current Special Real Time 0|>era ting System time and the first 
PATCH not occurring for almost 24 hours. Also this allows distribution 
of the time management processing by offsetting ADJ time relative to 
a standard time. 
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STOP = 

Specifies ♦ he Special Real Time Operating System system time after 
which no more PATCHes are issued. If REL is specified, or if the 
operand is omitted, the stop time is equal to the current Special Real 
Time Operating System time plus the time value in the remainder of 
the operand. If TOD 'is specified, the stop time is equal to the time 
value in the remainder of the operand. If iDJ is specified, the stop 
time is calculated by assuming the time value in the operand to be a 
TOD value except that the interval time is repeatedly addad to the 
assumed TOD time until that value is greater than the current Special 
Real Time Operating System time. When either REL, TOD, or ADJ is 
specified and the stop time is less than the calculated start time, 
a 24-hour value is added to the stop time until the STOP time equals 
or exceeds the START time« 

C001IT= 

Is equal to the number of PATCHes that are issued before the PTIHE 
control block is deleted. This operand is an alternative to STOP^:. 
The count value can be specified in a register, but must not exceed 
a halfvord value. 

Note: If both STOP= and C001IT» operands are specified, the COOMT field 
Hill be ignored. If neither operand is specified, the PTIHE is 
assumed to be infinite, and PATCHes will be issued until a PTIHE 
DEL or HOD is issued for that task and/or entry point name. 

INTFfAL* 

Is the interval between successive PATCHes. If this operand is omitted 
or less than the STSGEHed time interval, the STSGEHed time interval 
will be substituted. The time may be specified vith the A^^ suboperand 
as described above. 

POBGEs 

Provides a method of deleting the task associated with a PTIHE. This 
operand can be specified when the PTQE is created (i.e., with ADD or 
HOD) or when the PTQE is deleted (DEL). If PURGE' (0,C,or ff) is 
specified, & DPATCH is issued when the PTQE is deleted. The operand 
a, C, or W, specifies the type of DPATCH to be issued (see DPATCH 
description) . If the task is to be deleted when the PTQE is deleted 
automatically via the STOP or COUNT operand, the PORGE operand must 
be specified in an ADD or HOD PTIHE for the PTQE. Specification of 
the PORGE operand with a DEL type overrides the operand specified when 
the PTQE was created. 

PTID« 

Is a four byte value used to uniquely identify a PTQE. If this operand 
is omitted on a PTIHE ADD request, the Special Real Time Operating 
System will assign a PTID. The PTID is returned to the user in 
Register 1 on PTIHE ADD or HOD requests. PTID of a fullword of zeros 
or blanks will be ignored. If register notation is used, the specified 
register must contain the ID to be used. 

HP* 

Are the list and execute forms of PTIHE which are generated by 
specifying HF=L and HF» (E, ad dress) , respectively. The list and execute 
forms are not valid with the RET option since this form has no 
parameter list. Also, the PATCH operands cannot be specified with 
HP«L. 

DC?TR«r 

Where r is the general purpose register (2-12) that contains the 
address of the XC7T. 

DC?TLOC= (r) 
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Where r is the general purpose register (2-12) enclosed in parentheses 
having the address of a U-byte memory location that contains the 
address of the XCVT. 

DC VTLOC= address 

Where address is the label of a 4-byte memory location that contains 
the address of the XCVT, 

PATCH Operands 

Specifies the PATCH to be issued. Any valid combination of PATCH 
operands can be specified. Note that the PATCH supervisor and/or 
program parameter list can be expended with the list form of PATCH 
and then specified in execute form, i.e., SO PL= (E, addr) , 
PEOBL= (E,addr) - 

Note that there are some restrictions to the use of PATCH parameters 
with PTIME: 

QPOS= 

DPATCH cannot be specified. LAST will be substituted. 

FREE= 

Can be specified, but the FREEMAIN will not be executed until the 
PTIME queue element (PTQE) generated by this PTIWE is deleted. If 
the PTQE is not repeating, this will be like a normal PATCH. 

When control is returned, register 15 contains one of the following 
return codes: 



Option 
Code ^"^^^^^ 


RET 


ADD 


MOD 


DEL 


0 


Successful 


Successful 


Successful 


Successful 


4 


NA 


Interval time less 


Interval time less 


NA 






than SYSGEN time 


than SYSGEN time 








interval- -SYSGEN 


interval- -SYSGEN 








time interval 


time interval 








substituted 


substituted 




8 


NA 


NA 


PTQE not found 


PTQE not found 


12 


NA 


NA 


TASK or EP name 


TASK or EP name 








not specified 


not specified 


16 


NA 


No CBGET area 


NA 


NA 


20 


NA 


Duplicate PTQE 


NA 


NA 






(i.e.. a PTQE 










already exists 










with the same 










PATCH Parameter 










and PTID value.) 






24 


NA 


Invalid PATCH 


Invalid PATCH 


Invalid PATCH 






parameters 


parameters 


parameters 






(e.g., invalid 


(e.g., invalid 


(e.g., invalid 






ECB address) 


ECB address) 


ECB address) 



When the return code is 8 or greater, the PTIME was not successful, 
and the existing PTIWE specification will not be changed. 
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TIME ARRAY (DPPCTIMR) : 



♦TIMED 
+ *** 
+ * 

+TIMEHS 

+TIMETOD 

-fTIMEJDAY 

♦TIMEMDAY 

+TIMEEBC 



DS ECT 



TIME ARRAY DSECT 



DC 
DC 
DC 
DC 
DC 



pi o» 

F« 0» 
F« 0« 
F' 0« 



TOD IN 10 MIL UNITS 

TOD IN 10 MIL ONITS-HHMMSSTH 

JULIAN DATE-OOYYDDDC 

DAY OF MONTH DATE-OMMDDYYC 



CL 1 0 • « 



EBCDIC DATE-DD/MMM/YY 



PTIME INPUT PARAMETERS: 

♦PTIMEL DSECT 
+ *** 

+* PTIME INPUT PARAMETERS 







REG1=ADDR OF 


SUPERVISOR LIST (IF REG 


0 ZERO) 






REGO=0 = RET 


OPTION 








=4 = ADD 


OPTION 








=8 = MOD 


OPTION 








=12= DEL 


OPTION 














+PTIMSFLG 


DC 


XL 1 ' 0 ' 


TIME OPTION FLAG 




+PTIM5TRT 


DC 


AL3 (0) 


START TIME VALUE (OR 


ADDRESS) 


+PTIMIFLG 


DC 


XL 1 ' 0 • 


PURGE OPTION FLAG 




+PTIMINTL 


DC 


AL3 (0) 


INTERVAL TIME VALUE 


(OR ADDRESS) 


+PTIMEFLG 


DC 


XL 1» 0' 


TIME OPTION FLAG 




+PTIMSTOP 


DC 


AL3 (0) 


STOP TIME VALUE (OR 


ADDRESS) 


+ 


ORG 


PTIMSTOP 






+PTIMCNT 


DC 


ALB (0) 


COUNT VALUE 




+PTIMPTCH 


DC 


A(0) 


PATCH SUPERVISOR LIST 


+PTIMPARM 


DC 


A{0) 


PATCH PROBLEM LIST 




+PTIMPTQE 


DC 


A(0) 


PTQE ADDRESS 




+PTIMLNGH 


EQU 


*- PTIMEL 










PURGE OPTION FLAGS 




+PTIMFPRG 


EQU 


X' 01 • 


PURGE DPATCH=U 




+PTIMFDPC 


EQU 


X' 02» 


PURGE DPATCH=C 




+PTIMFDPW 


EQU 


X' 04» 


PURGE DPATCH=W 




+ * 




TIME OPTION FLAGS 




+PTIMCFG 


EQU 


X« 08' 


THIS FIELD CONTAINS 


COUNT VALUE 


♦PTIMREL 


EQU 


X' 01 ' 


RELATIVE TIME 




+PTIHTOD 


EQU 


X' 02' 


TOD TIME 




+PTIMA3J 


EQU 


X' 04' 


ADJUSTED TIME 




♦PTIMA3DR 


EQU 


X' 80' 


THIS FIELD CONTAINS 


TIME ADDRESS 


+PTIMIN 


EQU 


*-PTIMEL 
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VALID PTIME OPERAND COHBI NATIONS: 



Operand 


Option 


ADD 


MOD 


DEL 


RET 


START 


0 


0 






STOP 


O 


0 






COUNT 


O 


0 






INTRVAL 


0 


O 






PURGE 


O 


0 






MF 


0 


0 






DCVTR 


O 


O 


O 


0 


DCVTLOC 


O 


0 


O 


0 


PATCH operands 


R 


R 


R 





070372 



R = Required 
O = Optional 
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PURGEWQ 



The PORGEWQ macro is used to selectively purge work requests to a 
specified independent Special Real Time Operating System task or queue 
holder. The selected work requests will be removed from the active 
work queue (i.e., a chain of work requests that have been generated in 
response to PATCH macro calls but have not been executed yet) or from 
the DPATCH work queue (i.e., a work request generated in response to 
a PATCH OPOS=DPATCH. . . macro call). Other work requests for that task 
will not be purged and will be allowe^ to execute normally. 



symbol 



PURGEWQ 



ID =( 1 
(value ) 



,PTN= 



OWN , 
I FIND I 
I MASTER I 
. SLAVE J 



l^FREE ( (length ),( address 



( NOPOST 
,OPT - I WAIT 



(r) 

(POST, ( ECB addr 



, DCVTLOC = j^^^^j 
,DCVTR = (r) 



,MF = {(E, ((r) 
(addr 



where 'r' is a general purpose register (2-12) 



SUPL = 

Specifies a list form of the PATCH supervisor operands. PURGEWQ uses 
this list to obtain the entry point name, task name, and partition 
reference. The SUPL= option allows the user to use the same SUPL for 
PATCH macro calls and the PURGEWQ macro call. If register form is 
specified, the register contains the address of the SOPL. 



EP= 

Specifies a 1 to 8 character valid program name which is the name of 
the program that is scheduled to be executed in response to a previous 
PATCH macro call. Th<^ entry point name is used in conjunction with 
the ID value to identify the work requests to be purged. If register 
form is specified, th«; register contains the address of an 8-character 
field which contains .he program name. The name must be on a fullword 
boundary, be left- just if ied and padded on the right, if necessary, to 
complete eight characters. 

TASK= 

Specifies a 1 to 8 ch racter name which is the name of a previously 
created independent tc sk being referenced by this PUfiGEWQ. The task 
name identifies the task for which work requests are to be purged. 
If omitted, the current task is assumed to be the one for which work 
requests are to be purged. If register form is specified, the register 
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contains the address of an 8-character field which contains the task 
name. The name must be on a fullword boundary, be left- just if ied and 
padded on the right with blanks, if necessary, to complete eight 
characters. 

?TN = 

In two-partition operation, this operand specifies the target partition 
for this PORGEWQ. OWN means that the target partition is the partition 
that executes the PURGEWQ; MASTER defines the master partition as the 
target partition; SLAVE defines the slave partition as the target 
partition; FIND causes the PURGE WQ subroutine to search for the 
specified task in the partition that executes the PORGEWQ; if it is 
not found, the other partition is searched- OWN is the default option. 

ID= 

Spt^cifies a decimal value from 0 to 254 to be used in conjunction with 
th? entry point name to identify the work requests to be purged. This 
i5 , the ID that was passed as a parameter on a previous PATCH macro 
Cc 11. A PORGEWQ request with an ID of 255 will cause all work requests 
t- the specified task with the specified entry point name to be purged 
r gardless of the ID value specified on the originating PATCH macro. 
I ID is omitted, a default value of 0 is assumed- If register form 
i: specified, the register must contain the ID value in the low- order 
b^ te. 

FR};s= 

Specifies the length and address of a GETMAINed area that is to be 
FFEEHAINed when the last specified work queue has been purged. Both 
the length and address are required and identify the area of storage 
to be freed- Either the length or address or both may be in registers. 

OPT= 

Specifies the PORGEWQ option used to determine if the t ^er is to be 
notified when all specified work requests have been pur jed or, in the 
case when a work request to be purged is currently acti e, ha\ e been 
completed. NOPOST indicates that the specified work re uests are to 
be scheduled for purging but control is to be returned o the user 
and no indication will be made when the work requests h. ve actually 
been purged. WAIT indicates that the user is to be pla. ed in a wait 
state until all specified work requests have been purgec or, if a work 
request to be purged is currently active, until that work request has 
completed normal processing. POST indicates that the specified work 
requests are to be scheduled for purging but control is to be returned 
to the user. The user will be notified via a POST to the specified 
ECB whenever all specified work requests have been purged or, if a 
work request to be purged is currently active, when that work request 
has completed normal processing. If register form is specified on 
the OPT = POST parameter, the register contains the address of the 
ECB to be posted. 

DCVTLOC= 

Specifies the address of a U-byte memory location that contains the 
address of the XCVT. If register form is specified, the register must 
contain the address of the location that contains the address of the 
XCVT. 

DCVTR= 

The register specified contains the address of the XCVT- 
HF= 

Specifies the list to execute form of the PORGEWQ which are generated 
by specifying MF=Land MF=(E, address) respectively. The list form is 
not valid with the SOPL parameter- 
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Note: The EP , TASK, and/or PTN i araiaeters cannot be used with the SUPL 
parameter. Either the SDFL or the EP parameter must be 
specified. 

After completion of a PURGEWQ macro cai 1 Register 15 will contain a 
return code and register 1 will contain a count of the number of work 
requests purged or zero ( depend i i g on the return code). This count of 
work requests purged does not include the current work request, if 
applicable, since it was hot actually purged. 

R egis ter, ,15 Register 1 Descriptio n 

0 No, of work Successful completion 

requests purged 



12 
16 



NO. of wor?c 
requests purged 

0 

No. of wor 

requests s- heduled 
to be purgr:;d 



Task was dormant (no active work 
regues ts 

One of the work requests is the 
currently active work request 

No work requests found to be purged 

OPT= (POST, ECB addr) specified but 
due to PATCH return code, we are 
unable to WAIT until all work 
requests have been purged before 
posting the user ECE 



20 



DPATCH in progress for this task 



2a 0 Invalid PTN= specified 

28 0 Invalid input address or unable to 

locate specified task. 



32 No. of work Task was for the current task and 

requests purged OPT=WAIT was specified. This may 

cause an interlock situation. 
Therefore the WAIT request is 
ignored- 
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PUTARRAY 



The PUTARRAY macro is used to move data into one or more VS resident 
arrays of the data base. The data in the entire array based on the 
length defined through the offline utility will be replaced. This 
macro is not valid for use with blocked arrays. Where incr is 
specified, it may be any value from 1 to 255. 



The parameters NOMBER=, NAME=, NAMELST=, ADDRLST=, and NUMBLST are 
mutually exclusive; only one may be specified, 

NAME= 

Is an 8-character name of a single array into which data is to be 
moved. 

NUMBER= 

Is an array number of a single array into nhich data ±3 to be moved, 
DATA= 

Is used with NAME= or NUf!BER= operand, "he address from which data 
is to be moved into the specified array. 

NRMELST= 

Is the address of a list of 8-character array names for which data is 

to be moved. Incr is the value by which this address is to be 
incremented to locate the next name. If not specified, a value of 8 

is assumed. The list must be terminated by a byte containing X*FF' 

in the position that would be occupied by the first byte of the next 
name. 

ADDRLST= 

Is the address of a list of data base array addresses as returned from 
a previous execution of the GETARRAY macro with NAME, NAMELST NUMBER, 
or NUMBLST specified and TYPE=ADDR. Incr is the value by which this 
address is to be incremented to locate the next array address. If 
iocr is not specified, a value of 8 is assumed. If specified, must 



[symbol] 



PUTARRAY 
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be no less than 8- The list must be terminated by four bytes 

CO taining X 'FFFFFFFF* in the position that would be occupied by the 

ad' ress of the next array. If the GETAERAY macro, TYPE=ADDR, and 

NAi ELST or NUMBLST is used to build the list, it will place this flag 

at the end of the list. 

NUM. LST= 

Is the NUMBLST parameter that specifies the address of a list of 2-byte 
fields containing array numbers for which data is to be written. Incr 
is the value by which this address is to be incremented to locate the 
next number. If incr is omitted, a value of 2 is assumed. A value 
less than 2 must not be specified for incr. The list must b« 
terminated by a byte containing X'FF* in the fir^t byte of the 2-byte 
field which would be occupied by the next array number. 

EXAMPLE: Number List 



n7n 

2 

H'2?5' I 

H 139 1 

6 .1 

X'FP- 



DATALST^ 

Is the address o a list of addresses into which the data from the 
specified array (s) is to be moved. The list must contain an entry 
for each array for which data is to be ; oved. This entry will contain 
a fullword address which identifies the memory address frooi which the 
first byte of the array data is to be moved. Incr is the value by 
whicii the address of the list is to be incremented to pick up the 
memory address to which the next array is to be moved. If incr is 
not coded, a value of 4 is assumed. If specified, must not be less 
than U- 

DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC= (r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses that has the address of a U-byte location that 
contains the address of the XCVT. 

DCVTLOC=address 

Where 'address* is the label of a 4-byte location that contains 
the address of the XCVT. 

After execution of the PUTARRAY request, the return code in register 
15 is set to zero to indicate successful completion or to four to 
indicate that the request could not be satisfied. This may be because 
of one or more of the following reasons: 

• One or more of the named arrays is not defined to the system. 

• A numbered array was requested which is higher than the highest 
numbered array defined to the system, 

• A TYPE=DATA request was made for a direct access resident array. 
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PUTBLOCK 



The PUTBLOCK macro will retrieve the data from user-allocated storage 
and place that data into blocked arrays. The macro may be used to 
write one or more blocks of data into one or more arrays. The arrays 
may be either virtual storage or direct access resident. 



[symbol] 



PUTBLOCK 



NAME= 



( name ) 
I (r) j 



NUMBER= 



NAMELST= 



j number \ 
\ (r) f 

j addres s ) 
I (r) f 



_ I address \ 
~ i (r) / 



NUMBLST 



,DATALST= {^']%^'''' 



,DCVTR= r 



, DCVTLOC= 



address 
(r) 



The parameters NAME^ NUMBER, NAMELST and NUMBL.'T are mutually exclusive. 
The macro will not expand if more than one of hese parameters is 
specified or if all of these parameters are om tted. 

DCVTR= 

Specifies a register (2-12) which contains the address of the XCVT. 
DCVTLOC= 

Specifies the address or a register (2-12) enclosed in parentheses 
which contains the address of a location which contains the 
address of the XCVT. 

NAME= 

Specifies the name or a register containing the address of the name 
of a named array into which data is to be written. 

NUM3ER= 

Specifies the number or a register containing the number assigned to 
a numbered array into which data is to be written. 

NAMELST= 

Specifies the address or a register (2-12) which contains the address 
of a user-constructed list of array names into which data blocks are 
to be written. The name list will be a table of 8-byte entries with 
one valid array name in each entry. The first byte past the last 
valid entry will be set to X'FF* to indicate the end of the name list. 
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EXAMPLE: Name List 



ARRAYNAM 



HOUSTONb 
161 



TEXASbbb 

241 



X'FF 



NUMBLST= 

Specifies the address or a register (2-12) which contains the address 

of a user-constructed list of array numbers into which data blocks 

are to be written. The number list will be a table of halfword entries 

with one valid array number in each entry. The first byte past the 
last valid entry will be set to X'FF* to indicate the end of the number 
list. 



HT 



H'255' 



H'139' 



X'FF 



2 
4 
6 



DATALST= 

Specifies the address or a register (not register 1) which contains 
the address of a user-constructed list of block numbers and of 
address from which the data blocks are to be moved. The data list 
will be a table of 6-byte entries. Each entry will contain a 1-byte 
flag field, a 3-byte area address and a 2-byte block number. 



DATA LIST ENTRY DESCRIPTION: 



FLAG 
BYTE 



AREA ADDRESS 



BLOCK 
NUMBER 



FLAG BYTE 

X*40' — Indicates the last entry to be processed for a 

particular entry in the name list or number list. 

X'80' — Indicates the last entry in the data list. 

AREA ADDRESS — The address of a user-allocate area of storage from 

which the data block is to be oved. The area must 
contain the entry data block tc be placed in the 
block. 
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BLOCK NUMBER — The number assigned to the data block to be retrieved 

and placed in the array described in the Name List 
or Number List» 

EXAMPLE: Data List and Name List 



Name List 
FlRSTbbb 



SECONDbb 



THlRDbbb 



X'FF 



Data List 





A(Area) 


H'i' 




A( Area) 


H'5- 


X'40' 


A(Arca) 


H'lO' 


X'40' 


A(Ari.-a) 


H'3' 




A( Area) 


H'255' 




A(Area) 


HT 




A(Area) 


H'2" 




A(Area) 


H'3r 




A( Area) 


H'186' 


X'80' 


A(Area) 


H'249' 



Blocks in first 
array 

Blocks in second array 



Blocks in third array 



Note: A zero returned in register 15 indicates successful completion. 
A non-zero returned in register 15 indicates that one or more 
errors were encountered during processing of this PDTBLOCK 
request. The high-order byte in register 15 contains a count 
of the number of errors encountered and the low-order three 
byces contain the address of the first invalid array name or 
number . 
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The PUTITEM macro is used to store data into one or more items of the 
data base. If another user of the data base is executing a data base 
access macro with PROTECT=YES, the operation of the POTITEM macro will 
be delayed until all other users of the data base which have specified 
PROTECT=YES complete. This macro is not valid for use with direct 
access resident arrays. Where incr is specified, it may be any value 
from 1 to 255. 



[ symbol ] 



PUTITEM 



NAME= name 



NAMELST= ({^^^^33} [, inorl) 
ADDRLST= ({3^5^333} [, incrl) 



,DCVTR= r 

,DCVTLOC= {^^ll^^^} 



The parameters NAriE = , NAMELST=, and ADDRLST are mutually exclusive; 
only one may be specified- 

na;ie= 

Is an 8-character name of a single item for which data is to be stored. 
NA:iELST = 

Is the address of a list of 8-character ITEM names for which data is 
to be moved. Incr is the value by which this address is to be 
incremented to locate the next name. If not specified, a value of 8 
is assumed. If specified, the value must not be less than 8. The 
end of the list must be indicated by a byte containing X'FF* in the 
position that would be occupied by the first byte of the next name. 

If the items are contained in blocked arrays, the block number for 
which data is to be retrieved must be specified in the half word 
immediately following the 8-byte name. Also, the BLKNO=parameter 
should be specified and the incr must be coded as at least 10, 

ADDRLST= 

Is the address of a list of data base item addresses as returned from 
a previous execution of the GETITEM macro with NAME= Qr NAMELIsr= 
specified and TYPE=ADDR. Incr is the value by which this address is 
to be incremented to locate the next item address. If incr is not 
specified, a value of H is assumed. The end of the list must be 
indicated by a 4-byte field containing X'FFFFFFFF' in the position 
that would be occupied by the next address. If the GETITEM macro with 
NAMELST option is used to build this list, it will place that value 
at the end of the list. 
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DATA= 



Is the address from Mhich the first data is to be moved. Data vill 
be moved to the first ITEM specified, according to the length defined 
for that ITEM in the data base. Incr is the value by which the data 
address is to be incremented to determine the address to pick up the 
next data. If incr is not coded, the length of the items is used. 

BLKNO= U 

number 

If U is specified or if the parameter is omitted, the array is 
unblocked. A number is used to specify that the data is to be 
retrieved from a blocked array (s). If NAME= was specified, number is 
the block number from ahich data is to be retrieved. If NAMELST= is 
specified, any number from 1 to 32767 may be coded to indicate that 
the nlock numbers are coded as part of the NAMELIST=- 

DCVTP=r 

Where 'r* is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC=r 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses that has the address of a 4-byte location that 
contains the address of the XCVT. 

DCVTLOC=address 

Where 'address' is the label of a U-byte location that contains 
the address of the XCVT. 

When control is returned, register 15 contains one of the following 
return codes: 



Decimal 
Code 



Desc ri pt io i 



0 



Successful execution. 



One or more of the item names specified could not be 
resolved or data was requested to be moved for the item 
with defined length of 0 bytes. 



8 



Invalid options were passed to the POTITEM routine 
(probably the macro expansion had been modified). 



12 



A block number was specified for an unblocked array or 
a block number was specified that is greater than the 
highest block number defined for the array. 



16 



PUTITEM request for an item that is contained in a direct 
access array. 
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PUTLOG 

The PUTLOG macro logs data base arrays on demand. 



[symbol] 



PUTLOG 



NAME= 



NUMBER= 



(r) 

number 
(r) 



NAMELST= 



NUMBLST= 



LLOGHDR= 



address 
(r) 

address 
(r) 

address 
(r) 



j,BLKLIST=^| address [,incr] 



,PROTECT= 



LdCVTR= r 



,DCVTLOC= 



RISK 
YES 



address 
(r) 



The parameters NAME, NUNBEP, NAMELST, AND NUMBLST are mutually 
exclusive. The macro will not expand if more than one of these 
parameters is specified or if all of these parameters are omitted. 

DCVTR= 

Specifies a register (2-12) which contains the address of the XCVT. 
DCVTLOC= 

Specifies the address or a register (2-12) enclosed in parentheses 
which contains the address of a memory core location which contains 
the address of the XCVT, 

NAME= 

Specifies the name or a register (2-12) which contains the address of 
a name of a named array from which data is tc be logged. 

NUMBEF= 

Specifies the number or a register (2-12) containing the number 
assigned to a numbered array from which data is to be logged. 

NAMELST= 

Specifies the address or a register (2-12) which contains the address 
of a user-constructed list of array naires fron which data is to be 
logged- The name list will be a table of 8-byte entries with one 
valid array name in each entry. The first byte past the last valid 
entry will be set to X'FF» to indicate the end of the name list. 
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EXAMPLE: Name List 



0 



ARRAYNAM 
8 



HOUSTONb 
16 



TEXASbbb 
24 



X'FF 



NUnBLST= 

Specifies the address or a register (2-12) which con :ains the address 
of a user-constructed list of array numbers from which data is to be 
logged. The number list will be a table of halfword entries with one 
valid array number in each entry. The first byte past the last valid 
entry will be set to X*FF» to indicate the end of the number list. 



EXAMPLE; Number List 



HT 



H'255' 



H'139' 



X'FF 



LOGHDR= 

Specifies an address or a register conta: ning the address of any array 
logging header- Information in this logging header will identify the 
copy of the array which is to be replaced in the log data set. The 
LOGHDR parameter cannot be specified if the BLKLIST parameter is 
specified. 

The logging header is a 2U-byte control block which precedes the array, 
both as the array exists in virtual storage and as it is written to 
the logging array. The logging header which was retrieved as part of 
a previous GETLOG macro may be used to replace that copy in the log 
data set. 



BLKLIST= 

Specifies the address or a register (2-12) which contains the address 
of a user-constructed list of block numbers and of core addresses from 
which data blocks are to be moved. The data list will be a table of 
6-byte entries. Each entry will contain a 1-byte flag field, a 3-byte 
area address, and a 2-byte block number. This will allow the user to 
update selected segments of the DA log array for block VS resident 
arrays on demand basis. The latest log copy will be modified. 
However, the entire VS resident block is not necessarily logged; only 
the log block which contains the VS resident block specified will be 
updated. The actual log copy will not change when using this 
parameter; that is, repeated PUTLOG macro calls with BLKLIST parameters 
will update the same log copy. 



BLKLIST ENTRY DESCRIPTION: 
0 1 2 3 4 



FLAG 
BYTE 



AREA ADDRESS 



BLOCK 
NUMBER 
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FLAG BYTE 



X»40» 
X*80' 

AREA ADDRESS — 
BLOCK NUMBER — 



Indicates the last entry to be processed for a 
particular entry in the name list or number list. 

Indicates the last entry in the data list. 

Not applicable for PUTLOG, The area is allocated 
so that list forms of PUTLOG and PUTBLOCK are the 
same. 

The number assigned to the data blocJc to be retrieved 
and placed in the array described in the name list 
or number 1 .st. 



EXAMPLE: BLKLIST and Name Lisr. 



Name Lii>l 



FIRSTbbb 



SECONDbb 



THIRDbbb 



X'FF 





A(Area) 


HT 




A( Area) 


H'5" 


X'40' 


A(Area) 


H'lO" 


X'40' 


A(Area) 


H'3' 




A(Area) 


H'255' 




A{Area) 


HT 




A(Area) 


H'2' 




A(Area) 


H'37' 




A(Area) 


H'186' 


X'XO' 


A(Area) 


H'249' 



Blocks in first 
array 

Blocks in second array 



Blocks in third array 



PROTECT= 

If YES is specified, a lock will be set to prevent other programs that 
rpecify PROTECT=YES from accessing the data base while this PUTLOG is 
n the proces.'j of modifying the data base. If RISK is specified, the 
ata will be moved without regard to other programs which may be 
ccessing the data base. 

^ )te: A zero returned in register 15 indicates successful completion. 
A non-zero return^ad in register 15 indicates that one or more 
errors were encountered during processing of this PUTLOG reguest. 
The high-order byte of register 15 contains a count of the number 
of errors encountered aad the Idw-order three bytes contain the 
address of the first invalid arfay name or number. 
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RECORD 



The RECORD macro is used to write data from programs in execution to 
a sequential data set. The data in the data set can then be retrieved 
at a later time through the playback function. 



[symbol] 



RECORD 



ID 



{number? 



ADDR: 



i address/ ' 



C0UNT= i \ 
I number) 



,DCV'fR= r 



; DCVTL0C= 



i (r) ) 
(address) 



ID= 

Is a unique 3-digit hex number (001-FFF) which identifies the data 
that is to be recorded (written) to a sequential data set« If (r) is 
specified, the register must contain the 3-digit hex number, 

ADDa= 

Is the address of the data that is to be recorded. If (r) is 
specified, the register must contain the address of the data to be 
recorded. 

COUNT= 

Is the number of bytes that is contained in the data. The maximum 
size is 65525 bytes. If (r) is coded, the specified register must 
contain the number of bytes to be recorded. 

DCVTR=r 

Where 'r' is the general purpose register (2-12) that contains the 
address of the XCVT. 

DCVTLOC= (r) 

Where 'r' is the general purpose register (2-12) enclosed in 
parentheses that has the address of a 4-byte location that 
contains the address of the XCVT. 

DCVTLOC=address 

Where 'address* is the label of a 4-byte location that contains 
the address of the XCVT. 



Code 


Description 


00 


Normal Completion 


04 


ID is Disabled 


12 


End of data set reached 




or I/O error on output 




of data record. All data 




recording is disabled for 




this job step. 



RETURN CODES. RECORD macro will issue return codes via register 15. 
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REPATCH 



When a PATCH forces a WQE to fall out of the queue {QPOS=FIP.ST is 
specified and the queue was full) , a Repatch List (EEPL) will be 
constructed if the failing PATCH had REPATCH option specified. The 
user's ECB will be posted with a completion code of X'U4« in the 
high-order byte and the address of the Repatch List in the three 
low-order bytes. 

Note: The three low-order bytes represent a REPL address only if the 

REPATCH option was specified and the completion code (high-order 
byte) is X »44' . 

Warning: If the RSPATCH option was specified, and the ECB is posted 
with X'4i4', a REPATCH macro must be executed, so that the 
Repatch List built from Special Real Time Operating System 
Control Block Storage can be freed- 



[symbol] 



REPATCH 



[, PATCH operand. . .] 
,DCVTR= r 



L \ 



,DCVTLOC= j Ji;^^^ 



REPL= (r) 

Where 'r' is the general purpose register (2-12) that contains the 
address of the REPL. 

REPL=address 

Where 'address' is the label of a 4-byte storage location that contains 
the address of the REPL, e.g., the label of the ECB that was posted 
with the address of the REPL. 

TYPE= 

Specifies whether the PATCH is to be retried (EXEC) or deleted (PURGE) . 
Only one REPATCH is permitted for every original PATCH. If TyPE=EXEC 
is specified and the WQE is pushed out again, no REPL will be built. 
A TYPE=PURGE causes the FREE=, if specified in the original PATCH, to 
be issued and the Repatch List to be freed. 
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PATCH Operands 

If any PATCH operands are specified ifith a REPATCH TYPE=EXEC, the 
REPATCH macro will internally invoke the PATCH macro and the code will 
be generated that modifies the REPL. Since the REPL supplied by the 
Special Reail Time Operating System is in protected storage prior to 
issuing a REPATCH macro with PATCH operands, the user must obtain 
storage (length=REPLLNTH) and copy the supplied REPL (for that same 
length) into his own storage. Since one of the words in the Special 
Real Time Operating System supplied REPL contains its own address, the 
user's REPL will also have this address so that the REPATCH SVC routine 
can free its storage. Several restrictions for PATCH operands follow: 

• SDPL, PROBL, ID, and PARAM must not be specified. 

• If PRTY or PRTYLOC is specified, both subvalues (name, priority) 
must be specified. 

• REPATCH option must not be specified. 

• Care must be taken in modifying FREE=operands since the original 
FREE request has not been processed. 

Specifying PATCH operands with a REPATCH TyPE=PURGE will not generate 
instructions to modify the Re patch List and will therefore have no 
effect on the execution of the REPATCH SVC routine. 

DCVTR=r 

Where «r' is the general purpose register (2-12) that contains the 
address of the XCVT, 

DCVTLOC=(r) 

Where »r' is the general purpose register (2-12) enclosed in 
parentheses having the address of a U-byte location that contains 
the address of the XCVT, 

DCVTLOC=address 

Where 'address' is the label of a U-byte location that contains 
the address of the XCVT. 

Note: The REPL DSECT can be obtained by the macro DPPXBLKS REPL=Y. 



REPATCH RETURN CODES: 
The REPATCH SVC routine returns a return code of 32 if an invalid TYPE 
or REPL address was specified. If the TYPE and REPL addresses are 
valid, the REPATCH SVC routine internally invokes the PATCH SVC routine 
and the return codes received upon return from PATCH are passed back 
to the user upon return from REPATCH. 
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CHAPIM_3. INSTALLATION GUIDE 



INIIQDDCTION 

Three distinct phases must be considered prior to building a Special 
Real Time Operating System: pre-SYSGEN, SYSGEN, and system 
initialization. In addition, there are certain considerations prior 
to generating the host 0S/VS1 system. These considerations and the 
building and running of the Special Real Time Operating System are 
discussed in the following sections. 

The pre-SYSGEN phase of building the Special Real Time Operating System 
consists of performing such functions as copying libraries, creating 
SYSGEN input, and allocating data sets, i.e., the normal preparatory 
work that must be done for any SYSGEN, 

The SYSGEN is the procedure by which the customer creates a Special 
Real Time Operating System tailored to his individual software 
requirements and hardware installation. SYSGEN comprises a series of 
0S/VS1 job steps for normal functions such as assemblies, link-edits, 
and copies. 

System initialization is the process through which the Special Real 
Time Operating System is brought into virtual storage and initialized 
for a realtime run. When initialization is completed, the Special Real 
Time Operating System is operating. 

In addition to building and running the Special Real Time Operating 
System, modifications may be made, to the data base for example, in an 
offline mode. To allow minor modifications without the necessity of 
a SYSGEN, an offline utility program is supplied with the Special Real 
Time Operating System. The use of this program is described in this 
section, as its primary function is the creation and modification of 
the customer's data sets. 



0S/VS1 SYSGEN CONSIDERATIONS 

The installation of the Special Real Time Operating System in an 0S/VS1 
system does not require any modifications to the VS system. However, 
certain 0S/VS1 facilities must be provided to the Special Real Time 
Operating System through the 0S/VS1 SYSGEN, and careful consideration 
should be given to other 0S/VS1 SYSGEN options. In addition, the 
requirements of related PRPQs being installed along with the Special 
Real Time Operating System must be considered. 



The Special Real Time Operating System requires three user-generated 
SVCs: a Type I, a Type II, and a Type 17. The SVC numbers may be any 
of the allowable 0S/VS1 user SVCs. The SVCs should be generated 
disabled. An example of the generation of the Special Real Time 
Operating System SVCs during the 0S/VS1 SYSGEN is shown below. 

SPECSVCS SVCTABLE SV C-255- D1 -S 0, * 

SVC-254-D2-S6, * 
SVC-25 3-DU-S6 

0S/VS1 has reserved the names lEAXYZl through IEAXYZ5 for CSECTs that 
must reside in the V=R nucleus. If the installation requires that the 
Special Real Time Operating System be SYSGENed with the Computer Status 
Panel or an external time source, a CSECT named IEAXYZ5 will be 
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generated. This precludes the use of this CSECT name by other programs 
that would reside in the nucleus. 



Careful consideration should be given to multiple console support 
routing codes in the 0S/VS1 SYSGEN, as they will affect the Special 
Real Time Operating System, (See MCS operand on vs SYSGEN macro.) 

The allocation for the SYSI.MACLIB data set should be made for 
BLKSI,ZE=6080, if possible, to allow for conformity with the Special 
Real Time Operating System source data sets A5799AHE. SOURCE and 
A 5799AHE . MSGFILE. If this size is not possible or practical, the 
Special Real Time Operating System data sets A5799AHE . SOURCE and 
A 5799AHE . MSGFILE must be reblocked to the block size of the customer's 
SYSI.MACLIB data set. Also, the data sets named by the MACDS ET=keywDrd 
and the ARRDSET=k.eywo rd must be allocated with the same block size as 
the SYSI.MACLIB data set. 

OIzSPECIAL REAL TIME OPERATING SYSTEM SYSGEN INITIALIZATION 

Certain preparations must be made prior to the Special Real Time 
Operating System SYSSEN, Data sets must be allocated, modules moved 
or copied, and the Special Real Time Operating System distribution 
tapes must be restored to a direct access device. 

The Special Real Time Operating System SYSGEN reguires (as input) the 
OS/VS 1 Stage 2 input stream in a sequential data set. This input must 
be saved when executing the OS/VS 1 SYSGEN for this purpose. 

The data sets required for the Special Real Time Operating System SYSGEN 
fall in to three categories, as shown in Figure 3-1. 



INPUT 



Distribution 



(Supplied) 



Data Sets 



Definition 



C'listomer 
(Dcriiiition) 



Data Sets 



OUTPUT 



SYSGEN 
Procedure 



T arget 



Customer 
Allocated 



Data Sets 



Figure 3-1. The Special Real Time Operating System SYSGEN Data Sets 

The Special Real Time Operating System distribution data sets that are 
required are distributed to the customer on the tape sent from the IBM 
program library. The three distribution data sets are: 

A5799AHE. SOURCE 

A5799AHE. OB JECT 

A5799AHE. MSGFILE 



The definition data sets are optional and are not required for a Special 
Real Time Operating System only, or for a Special Real Time Operating 
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System and Display Management SYSGEN- However, if they are used, the 
customer must allocate them- The four definition data sets are 
configuration, software options, display, and data base. They will be 
named and allocated by the customer and each must be a partitioned data 
set. 



The configuration and the software options data sets are required as 
input to Stage I of SYSGEN, only if the customer chooses to invoke the 
SYSGEN utility program D0MXSTG1 to do the SYSGEN. The alternative to 
invoking D0MXSTG1 is to code the Special Real Time Operating System 
SYSGEN macros in card image and to pass the cards to the OS/VSI 
assembler, as is done for an 0S/VS1 SYSGEN, 

If D0MXSTG1 is invoked, however, the configuration definition and 
software options data sets must be created prior to Stage I, The The 
data sets must be partitioned card image and must contain the following 

• Configuration Data Definitions — Each member must represent one 
System/7 or System/370 in the hardware configuration.. All 
configuration data for each system of a computer hierarchy must be 
in this one data set. Each member name must be of the form S7xx 

or S370xx, where xx is the CPU identifier of that particular system 
Macro statements in this data set must be those from the section: 
"Configuration Customer Definition Data Set Macros". 

• Software Options Definition -- Each member must represent one 
System/7 or one Systeffl/370 in the configuration. All software 
options data for either system of a CPD hierarchy must be in this 
one data set. Each member name must be of the form S370xx or S7xx, 
where xx is the identifier of that particular system. Macros in 
this data set must be those from the section: "Software Customer 
Definition Data Set Macros'". 



The display and data base data sets are optional. When these data sets 
are used, they provide additional input to the offline utility program 
when it is invoked during Stage II of the Special Real Time Operating 
System SYSGEN. Their presence, which signifies additional processing 
in Stage II, is indicated by pointing to the data sets by the DISDSET 
and DBDSET keywords on the GENEMS macro. When used, the data sets must 
be partitioned card image, with a BLKSIZE equal to the customer's 
SYSl.MACLIB data set and must contain the following: 

Data Base Definition Each member must contain at least one data 
base array definition that the customer desires to be placed in the 
final system by the SYSGEN process. All data base definitions for 
all System/370s and System/7s may be placed either in one data set or 
in separate data sets. 



The output is placed in the target data sets by the SYSGEN procedures. 
SYSGEN is informed of these data sets through the GENEMS macro, as 
described in the SYSGEN macros section of this manual. 



A number of OS/VSI macros are required by the Special Real Time 
Operating System. These macros exist on the OS/VSI distribution librar 
SYS1. AMODGEN. Prior to the Special Real Time Operating System SYSGEN, 
the required macros must be moved from SYS1. AMODGEN to SYSl.MACLIB. 
Below is an example of the JCL needed to move the required macros. The 
members named in the SELECT statements are the equivalent of a list of 
members that must be in SYS1, If the member is already in SYSl.MACLIB, 
it will not be copied. 
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//COPY 




JOB 


ACCOUNT, PR OGRA 


MMER 


// 




EXEC 


PGM=IEBCOPY 




// 




DD 


SYSOUT=A 




//DDIN 




DD 


DSN=SYS1. AMODG 


EN,UNIT=2314, 


// 






VOL=SER=TEST01 


,DISP= SHR 


//DDOUT 




DD 


DS N=SYS1.M ACLI 


B,DISP=0LD 


//SYSIN 




DD 


* 




COPY OUTD 


D=DDOUT, 


INDD= ( (DDIN, R) ) 




SELECT 


ME 


MBER= (IE 


FTI0T1 ,IHBPSINR, 


IKJTCB^IHAFLC) 


SELECT 


ME 


MBER= (IE 


FaCBOB,IEFJFCBN, 


IHAPDDT,IHARB) 


SELECT 


ME 


MBER= (IE 


ZDEB,IEZXRB, IHBR 


EL NO, CVT, SYNCH) 



The data shown underlined in the previous example will need to be 
changed to suit each customer's requirements. 

The Special Real Time Operating System modules are distributed on tape 
from the program library; however, prior to the Special Real Time 
Operating System SYSGEN, the distributed data sets must be restored to 
a direct access device. A job stream is provided as a first file on 
the distribution tape that will move the libraries. To execute this 
job stream, the user must first place in his SYS1.PR0CLIB a PROC named 
FPDSDEF. This procedure is the first job step encountered in the job 
stream in the distribution package. The only function of this PROC is 
to make DD statements available to succeeding job steps. 



The following statements are required in this procedure: 

//STEPABC EXEC PGM=IEFBR1 4 

//DOMVOL DD UNIT=SYSDA,DISP=OLD, 
// VOL=SER=PACK01 



The step name must be STEPABC; the DD card must be named DOMVOL and 
must have the volume serial number of the pack to which the Special 
Real Time Operating System modules are to be moved. 

After executing the described procedure as the first job step, 
subsequent job steps in the same job stream can determine the target 
pack for the Special Real Time Operating System modules by making a 
reference of the form: 



VOL =REF=*. A. STEP A EC. DOM VOL 

The following is an example of the JCL and control cards required to 
add procedure PPDSDEF to the SYS1 .PfiOCLIB. 



//ADDPROC 


JOB 


ACCOONXc' PROGRAMMER* 


// 


EXEC 


PGM=IEBDPDTE,PARM=» NEW 


//SYSaT2 


DD 


DSN=SYS1 .PROCLIB,DISP=OLD 


//SYSPRINT 


DD 


SYSO0T=A 


//SYSIN 


DD 


DATA 


./ ADD 




NAME=PPDSD EF,LIST=ALL 


./ NUMBER 




NEW1=0 0,INCR--=1.0 


//STEPABC 


EX EC 


PGM=IEFBR14 


//DOMVOL 


DD 


aNIT=SYSDA,DISP=OLD,VOL=SER=PACK01 


-/ 


ENDOP 


/* 







The data shown underlined in the preceding example will need to be 
changed to the customer's installation requirements. 
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with the member PPDSDEF in the SY SI . PROCLIB, the Special Real Time 
Operating System modules may be restored by entering the following 
start command on the 0S/VS1 console. 

START RDRT,181 , LABEL= (1 ,NL) 

Note: 181 should be replaced by the I/O device address where the 
distribution tape is mounted. 

If related PRPQs or program products are being SYSGENed along with 
Special Real Time Operating system, the Special Real Time operating 
System libraries should be restored first. If the Display Management 

PRPQ 5799-AFD is also being SYSGENed, it should be done next, followed 
by the restoration of other related products' tapes. 

If supplementary material has been ordered by the customer, the tape 
containing this material can be restored to disk by executing the same 
start command- 

The optional material is added to the existing distribution data sets. 
The basic material must be restored to disk before the optional 
material. When the optional material is restored, the disk data sets 
are already defined and cataloged. Consequently, the PROC PPDSDEF is 
not needed. 
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THE SPECIAL REAL TIME OPERATING SYSTEM DATA SET ALLOCATION 



The user must, prior to Stage II of SYSGEN, allocate target data sets. 
The following example gives the recommended space allocation required 



for the Special Real 


Time Operating System SYSGEN: 


VJ DU U O £i 1 


OJr Av^ £<-" 




LMDSET 


SPACE= 


(CYL, (1,1,50)) 


MACDSET - 


SPACE= 


(CYL, (1, 1,50)) 


ARRDSET - 


SPACE= 


(CYL, (1, 1,50)) 


DB1DSET - 


SPACE= 


(CYL, (2, ,50) ) 


DB2PSET - 


SPACE= 


(CYL, (2) ) 


DBUDSET - 


SPACE= 


(CYL, (2, ,50) ) 


PLIDSET - 


SPACE= 


(CYL, (1,1,50)) 


PLSDSET - 


SPACE= 


{CYL, (1,1,50)) 


FORDSET - 


SPACE= 


(CYL, (1,1,50)) 


These figures 


can be 


used in conjunction «ith the 



description of the GENEMS macro to allocate the Special Real Time 
Operating System target data sets. The above space is for a 3330 direct 
access storage device and is for a Special Real Time Operating System 
only SYSGEN. The DBIDSET, DB2DSET, and DB4DSET data sets may have to 
have larger space allocation depending on the user's data base and 
messages. If these data sets are not going to be supported by duplicate 
data set support, secondary allocation may be requested. 



FAILOVER/RESTART STORAGE REQUIREMENTS 

Failover/Rest art Write requires an amount of virtual address space 
determined by the following formula. In addition, the entire area is 
page fixed during Restart Write. 

Address space required = 12,288 + (k*2048) 

where k = (Tl + 8 ♦ 2047) /20U8 

and from the above calculation for k, 
k is the integer and any fractions 
are ignored. 

where T^ = Maximum blocksize of the device upon which 
the Failover/Restar t data set is allocated 
(13030 for a 3330, 7294 for a 2314, etc.) 

Example 

for a 3330, k would be 
k =. (13030 + 8 + 2047)/2048 
'k = 7 ignoring the fraction; 

therefore, the address space required 
= 12,288 + (7*2048) 
= 26,624 bytes. 

The entire address space used is released when Restart Write is 
completed . 

The amount of direct access space required for the Failover/Resta rt 
data set can be computed as follows: 

»'umber of tracks required =1*A + B + C-«-D + E 

where: A = Space required for the real storage portion of the 

data set 
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B = Space required for duplicating the active paging 

data set entries. 

C = Space required for the SYS 1 . SY SJOBQE dump 

D = Space required for the SHADS dump for the MASTER 

part it ion 

E = Space required for the SWADS dump for the SLAVE 

partit ion. 

In the following formulas the following terms and functions apply. 

Tl = Maximum blocksize of the Failover/Restart set 

Np = Number of active paging entries on the SYS 1- PAGE 

data set 

Dp = Number of devices containing SYS1.PAGE data sets 

R = Real storage size 

TRUNC = A function that takes the integer portion of a 
quantity only and discards the fraction 

N^jQ, = Number of 2U-byte records in SYS1. SYSJOBQE 

N^JQ2 = Number of 176-byte records in SYS1 . SYSJOBQE 

Ng^ = Number of records in SWADS for the MASTER partition 

N52 = Number of records in SWADS for the SLAVE partition 

, _ TRUNC (R/2048) , . 
^ - fRljNC(Tj^/2048 ^ ^ 

^ ~ TRUNC (T* /2056) ''' °^ 



"Q1 ] + TRLINC I 1 + 2 

TRUNC(T, /5J)/^ I TRUNC (Tj^/ 184 ' * ^ 



0 if SWA is used in MASTER partition; or 



D = TRUNC ^^,:„^L + 1 



SI 

TRUNC (T^/ 184) 



E = 0 if no SLAVE partition or SWA is used in SLAVE; or 



™C 1 tR^C(TL/184) I + ' 



Estimation of quantity N/P requires consideration of the size of the 
link pack area, BLDL list, JES options, numbers of partitions, and size 
and current allocation of active partitions. 
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THE SPECIAL REAL TIME OPERATING SYSTEM SYSGEN 



System generation (SYSGEN) is the procedure whereby the Special Real 
Time Operating System and associated PRPQs are combined to create a 
realtime system tailored to the needs of an individual user. The 
Special Real Time Operating System SYSGEN is analogous to the 0S/VS1 
SYSGEN procedure used to create an operational 0S/VS1 system. The 
Special Real Time Operating System SYSGEN is normally performed only 
when major changes to the system occur. Data of a more changeable 
nature is entered into the system through the offline utility. 

The Special Real Time Operating System SYSGEN process is patterned 
after the OS/VSI SYSGEN procedure. It is comprised of two phases. 
Stage I and Stage II. Stage I creates the job stream input for Stage 
II. Stage I can be executed either by using the Special Real Time 
Operating System utility D0MXSTG1 , or by directly invoking the OS/VSI 
assembler or the assembler H program product (5734- AS 1) to assemble 
the Stage I input cards. 

The direct implementation of the assembler method can be used if the 
Special Real Time Operating System only is being SYSGENed, or if the 
Special Real Time Operating System and the Display Management PRPQ 
(5799-AFD) are being SYSGENed- For the Special Real Time Operating 
System only, the required SYSGEN macros are coded and passed to the 
assembler. For the Special Real Time Operating System and the Display 
Management PRPQ, the macros are also passed to the assembler; however, 
care must be taken to ensure that the SYSGEN macros are properly 
sequenced for the member. (CONFIGH, DEFDEV, and GENEMS is the correct 
order. ) 

If other related PRPQ or program products are being SYSGENed, the 
utility program DOMXSTGl should be used. 

If the customer has coded his SYSGEN macros and configuration macros 
and placed them in configuration and software option definition data 
sets, DOMXSTGl may be used. This is shown in Figure 3-2. 



Configuration 
Data Set 



Software 
Options 
Data Sets 



Stage 1 
Input 
Macros 



OR 



DOMXSTGl 



Assember 



r 



Stage 2 
Job Stream 



Figure 3-2. The Special Real Time Operating System - SYSGEN - Stage I 
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The following statement is the JCL required to invoke the D0HXSTG1 



utility . 






//STG1 


JOB 


ACCOUNT, PROGRAMMER 


// 


EXEC 


PGM=D0MXSTG1 «,P ARM= ' S37 001^ 


//STEPLIB 


DD 


DSN=A579 9AHE.O BJECT,DISP=SHR 








//SOFTOPT 


DD 


DSW= (OSER CREATED) ,DISP=SHR 


//CONFG 


DD 


DSN= (USER CREATED) ,DISP = SHR 


//SYSPRINT 


DD 


SYSOUT=A 


//SYSUT1 


DD 


UNIT=S YSpA,SPACE= (CYL, 5)^ 


ZZSYSUT2* 


DD 


DNIT=SYSDA,SPACE={CYL, 5) 


//SYSUT3* 


DD 


UNIT=SYSDA ,SPACE=(CYL, 5) 


//SYSGO** 


DD 


UNIT=2 400,DISP = (,PASS) ,LABEL= (jliLi ^ 


// 




DCB= j[LRECL=80, BLKSIZE=800, RECFM=FB) 


//SYS IN 


DD 


DNIT=SYSDA^PACE^CYL^11l1JL1_ 


// 




DCB=:BLKSIZE=60 80 



*Not required for assembler H 
**If assembler H is used, SYSGO should be SYSLIN„ 



The JOB card should contain proper accounting information and any other 
data required in the customer's account. The PARM= field on the EXEC 
card identifies the system to be built. If the assembler H program 
product is to be used for the Stage I SYSGEH, the FARM field would be 
PARH='H,S37001 • . The SOFTOPT and COKFG DD cards must define the 
software options and configuration definition data sets respectively, 
as these data sets are customer built. The SYS0T1, SYS0T2, and SYSUT3 
DD cards may be coded to suit the customer's account- The The SYSGO 
(or SYSLIN for assembler H) DD cards specify the output data set, and 
if coded as shown in the previous example. Stage II of the special Real 
Time Operating System SYSGEN can be started by starting an OS/VSI reader 
to the data set, e.g., START RDRT , 1 80 , LAB EL= ( 1 , NL) . D0MXSTG1 will 
place the source code macros from the configuration and software options 
data sets in the SYSIN data set and pass it as input to the assembler. 

The output from the Stage I is an 0S/VS1 job stream which, when 
executed, comprises the Stage II of SYSGEN» Stage II creates the 
Special Real Time Operating System from the input data sets, and places 
the components of the system in the target data sets pointed to by the 
GENEMS macro. This is shown in Figure 3-3. 



OS/VS Li braries 



Distribution 

Afi799AHE:.SOURCE 
A5799AHF,. OBJECT 
A5799AHE.MSGF1LE 




Job 
Stream 
Start RDR 

>' 


1 *■ 


SYSI/NIJCLEUS 
SYSLSVCI.IB 

SYSLPARMLIB 
SYSl.MACLIB 

- 


>i 


SYSGEN 


* J 




Libraries 

Definition 

1 " ""1 

1 Displays I 
1 Data Base [ 




J»- 


Taraei 

User 
Created 



L _ _ -J Data Sets 

Data'S'ets 



Figure 3-3. The Special Real Time Operating System 
SYSGEN - Stage II 

One of the final steps of Stage II invokes the offline utility program. 
At this point the system-defined data base macros are processed. 
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followed by the customer definition data base macros (DBDSET=) . Then 
the system messages and the system displays (if Display Management is 
being generated) are processed. Following this, the customer-defined 
displays (DISDSET=) are processed by the offline utility. 

Warning ; The data base data sets are either partitioned or direct 

organization, and are built by the offline utility DPPXOTIL. 
The records and members of these data sets contain references 
to and have dependencies on other records and members. These 
references and dependencies are constructed by DPPXUTIL, 
and the data sets must not be modiifed except by DPPXaTIL. 
Concatenation of data base groups for realtime execution is 
not allowed. The macros used for SYSGEN and the available 
options are described in a following section- 



SYSGEN RESTART PROCEDURES 

The system generation process may come to an unsatisfactory completion 
because of errors that occurred during Stage I or Stage II, This 
section contains the information necessary to restart system generation. 

The most common errors during Stage I and the restart procedures for 
Stage I are discussed, as are the most common error causes during Stage 
II, the restart techniques, and the reallocation of data sets. 

The most common causes of error daring Stage I are keypunching errors 
in the input deck and contradictory or invalid specifications in the 
macro instructions. Keypunching errors are indicated by system 
generation error messages or assembler error indications. Invalid 
specifications are indicated with the system generation error messages 
printed in the SYSPRINT data set. If any errors are found during Stage 
I, the job stream is not produced. 

Stage I consists of a single assembly of the system generation macro 
instructions. It can be restarted only from the beginning. To restart 
Stage I, the errors in the input deck or in the definition data sets 
must be corrected and the job resubmitted. 

The most common error causes during Stage II are: 

• Machine interruptions and non -continuous machine time 

• Faulty space allocation of the system data sets during the 
preparation for system generation 

• Errors in the input deck that cannot be detected during Stage I 

• Procedural errors such as improper volume mounting 

Stage II can be restarted at the beginning of any job step. If any 
statements in the job stream are to be changed, the job stream must be 
on cards. If no statements are to be changed, the lEBEDIT utility 
program can be used to restart a job stream. A later section discusses 
the techniques used for restarting the job stream after any other 
necessary operations have been performed. The topics include restarting 
from cards, punching the job stream, and restarting from tape or from 
a direct access volume. 

If the job stream is on cards, a job step can be restarted by placing 
a JOB card ahead of the job step's EXEC card and entering the cards in 
the card reader. 

If the output from Stage I was not a card punch, the lEBPTPCH utility 
program can be used to punch the job stream. The following example 
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shows the statements required to punch the job stream using lEBPTPCH. 
The fields shown underlined £aay require modification for different 
installations. 



//PONCH 
// 



JOB 

EXEC 

DD 



PGM=IEBPTP CH 

UNIT=1.82rLABEL= (,NL) , VOL0ME=SEE=EXLABL » 
DISP=OLD,DCB= (RECFM=F, BLKSIZE=80) 
UNIT=2 5a0z2 
SYSO0T=A 



//SYSUT1 
// 



//SYSUT2 

//SYSPRINT 

//SYSIN 

PUNCH 



DD 
DD 
DD 



TYPORG=PS 



When using the lEBPTPCH utility program to punch the job stream, the 
following points should be considered. 



• The value of the UNIT parameter of the SYS0T1 DD statement is the 
specific unit address of the magnetic tape drive or direct-access 
storage device on which the j stream resides. Unless the job 
stream tape or direct-access volume has been dem«tunted, the value 
of this UNIT parameter is the same as the value of the UNIT 
parameter of the SYSGO or SYSLIN DD statement in the input deck 
for Stage I- If the job stream is on a direct access volume, the 
LABEL parameter must specify a standard labels and a DSNAME 
parameter must be specified. 

• The value of the VOLUME parameter of the SYS0T1 DD statement is 
either an external serial number assigned to the job stream tape 
reel, or the volume serial number of the tape or direct access 
volume. The system will issue a MOUNT command for the specified 
volume on the magnetic tape or direct access storage device 
indicated by the UNIT parameter. 

• Sequence numbers can be specified for the punched cards by putting 
the CDSEQ or CDINCR parameters in the PUNCH control cards of the 
lEBPTPCH input deck. 

The lEBEDIT utility program can be used to restart Stage II from any 
job step, after the first, when the job stream is on tape or a 
direct-access volume. To restart form the first- job step, a START RDR 
command can be issued for the tape drive or direct-access storage device 
that contains the job stream. 

IEBEDIT creates a new job stream by editing and selectively copying 
the job stream provided as input. The IEBEDIT utility program can copy 
an entire set of jobs including JOB statements and associated job step 
statements, or selected job steps in a job, as shown below in the 
control statements required by lEBEDIT when the job stream is on tape. 
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//RESTART 


JOB 






// 


EX EC 


PGM=IEBEDIT 




//SYSPRINT 


DD 


SYSOOT=A 




//£ YSUT1 


DD 


aNIT=xxx,L ABEL = (,NL) , 


X 


// 




VOLUME =SEB=serial^ 


X 


// 




DISP= (OLD, KEEP) , 


X 


// 




DSN=clata set name. 


X 


// 




DCB=(DCB information) 




//SYS0T2 


DD 


UNIT-xxx,LABEL=(,NL) , 


X 






VOL0MS=SER=ser ial. 


X 


// 




DISP== (,KEEP) , 


X 






DSK=clata set name. 


X 


// 




DCB= (DCB information) 




//SYS IN 


DD 


* 




EDIT 


START= 


SYSGENnn,STEPNAME=SGxx (, NOPRINT) 




or EDIT 


START= 


SYSGENnn,TYPE=INCLODE, 






STEPNAME= (SGXX (^SGXX) . ) (^NOPRINT) 




or EDIT 


START= 


SYSGENnn,TYP E=EXCLUDE, 






STEPNAME=(SGxx (^SGxx) - .. ) (^NOPRINT) 




/* 









when using the lEBEDIT utility program to restart Stage II, the 
following should be considered- 

• The value of the ONIT parameter of the SYS0T1 DD statement is the 
unit address of the magnetic tape drive or direct-access storage 
device on which the job stream tape or direct -acess volume is 
mounted. Unless the job stream has been demounted, the value of 
the DNIT parameter is the same as the value of the ONIT parameter 
of the SYSGO or SYSLIN DD statement in the Stage I input deck. If 
the job stream is on a direct -access volume, th6 LABEL parameter 
must specify a standard label, 

• The value of the VOLUME parameter of the SYSUT1 DD statement is 
either any serial number assigned to the job stream tape reel, or 
the volume serial nuaber of the tape or direct-access volume. The 
system will issue a MOUNT command for the specified volume on the 
magnetic tape drive or direct-access storage device indicated with 
the ONIT parameter. 

• The value of the UNIT parameter of the SYSUT2 DD statement is the 
unit address of a magnetic tape drive or direct-access storage 
device. If the job stream is on a direct-access volume, the LABEL 
parameter must specify a standard label. 

• One or more EDIT statements can be specified when executing lEBEDIT. 
If the TYPE parameter is omitted^ STSPNAME specifies the first job 
step in the job specified by the START parameter to be placed in 
the new job stream. 

• If TYPE=INCLUDE or TYPE=EXCLUDE is specified, STEPNAJJE specifies 
the job steps to be included or excluded, respectively, from the 
new job stream. Individual job steps and sequences of job steps 
can be specified for inclusion or exclusion. For example: 



STAET=SYSGSN4,TYPE=INCLUDE^STEPNAME=<SG3, SG6-SG9) 

indicates that job steps 3, 6^ 7, 8, and 9 of job U are to be 
included in the restart of system generation. 

• NOPRINT must be included if a listing of the new job stream is not 
desired. After the new job stream is created, a START RDR command 
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must be issued for the magnetic tape drive or direct-access storage 
device designated by the SYSUT2 DD statement. 

An lEBEDIT input deck for restarting Stage II is shown below. in this 
example, space allocation for SYS1.SVCLIB was not sufficient, causing 
the subsequent job steps to fail. 



//RESTART JOB 

// EXEC PGM=IEBEDIT 

//SYSPRINT DD SYSO0T=A 

//SYSUT1 DD UNIT=2400, LABEL= (, NL,) ,DSN = STAGE, X 

// VOL=SER=JOBSTM ,DCB= (RECFM=F, X 

// BLKSIZE=80,DEN=2) ,DISP= (OLD, KEEP) 

//SYSUT2 DD 0NIT = 2a00, DISP=(,KEEP) , X 

// VOL=SER=001234,DSN=OUTTAPE, X 

// LABEL=(,NL), X 

// DCB= (RECPM=F,BLKSIZE=8 0,DEN=2) 

//SYS IN DD * 

EDIT ST ART=S37001,TYPE= EXCLUDE, X 

STEPNAME= (SG1-SG24) 

/* 



The following section gives guidelines for restarting Stage II. 
Restarting may require the scratching and reallocation of space for 
the system data sets. When this is necessary, the following guidelines 
should be referenced for the procedure to be followed. After the 
necessary corrections have been made, the actual restarting of Stage 
II can be accomplished by one of the methods described. 

If the problem encountered is other than space allocation, e.g., 
component failures or machine malfunctions, the instructions printed 
out in the error messages or error codes should be followed. 

The method for reallocating space for a system data set depends on 
whether the data set contains data that must be saved. If the data 
set does not contain data that needs to be saved (for example, the data 
set will be re-copied completely when system generation is restarted), 
the lEHPROGM utility program can be used to scratch and reallocate 
space for the system data set. If the system data set contains data 
that roust be saved, the data will have to be copied into a temporary 
data set, space for the original data set will have to be reallocated, 
and the contents of the data set will be copied from the temporary data 
set into the reallocation data set. 

The input dec)c for scratching and reallocating space for system data 
sets must contain the following statements in the order shown: 

1- A JOB statement with any parameters required by the particular 
installation 

2. An EXEC statement with the PGH=IEHPROGM parameter 

3- A SYSPRINT DD statement defining the system output unit 

L A DD statement defining the unit address and serial number of 
the generating system's system resident volume: 

//SYSRES DD UNIT=unit ,VOLUME=SER=serial,DISP=OLD 

5. A DD statement defining any other permanent volume on which the 
system data sets to be reallocated reside: 
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//OTHEEVOL DD aNIT=uait , VOLO ME=SER=ser ia 1, X 
DISP=OLD 

6. A DD statement for each type of removable volume on Mhich the 
system data sets to be reallocated reside: 

//DDNAME DD U NIT= (uni t, , DEFER) , X 

VOLOME=PRI VATE,DISP=OLD 

7. A DD ♦ statement (SYSIN) 

8. A SCRATCH statement for each new system data set to be 
reallocated. The SCRATCH statement must have the following 
format : 

SCRATCH DSNAME=dsname, VOL=device=serial, PURGE 

9. A /* statement 

10. An EXEC statement with the PGM=IEHPROGM parameter 

11. A DD statement defining the unit address and serial number of 
the generating system's system residence volume (example shown 
above) 

12. A DD statement for each permanent volume on which the system 
data sets to be reallocated reside (example shown above) 

13. A DD statement for each type of removable volume on which the 
system data sets to be reallocated reside (example shown above) 

14- A SYSPRINT DD statement defining the system output unit 



15. A DD statement for each of the new system data sets to be 
reallocated. This DD statement must be the same as the one used 
in the input deck for the original allocation. 

//ddname DD DSNAME=dsnaffle, X 

// VOLUME= (, RETAIN, 3ER = serial) , X 

// UNIT=unit, LABEL=EXPDT=99350, X 

// SPACE= (allocation) ,DISP= (, KEEP) , X 

// DCB== (parameters) 

16. A DD * statement (SYSIN) 
17- A /* statement 



If the system data set to be reallocated contains data, one of two 
procedures can be followed- If there is enough space on the volume 
for a new space allocation, the following procedure may be used. 

1. Rename the system data set. 

2. Allocate space for the system data set (with its correct name) 
on the same volume using the lEHPROGM utility program. 

3. Copy the data in the renamed data set onto the newly allocated 
system data set using the lEBCOPY utility program. 

4. Scratch the renamed data set using the lEHPROGM utility program. 
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The following statement illustrates space reallocation for a data set 
on the same volume. The system data set to be reallocated is 
SYS 1 , PARMLIB. It tfas allocated space during the preparation for system 
generation with the following lEHPROGM DD statement; 



//PARMLIB DD DSNAME=SYS 1. PARMLI B, X 

// VOL0ME= (, RETAIN, SER=SySTEM) , X 

// DNIT=2314, DISP = (,KEEP) , X 

// SPACE= (TRK , (7, ,3) , ,CONTIG) , X 

// LABEL=EXPDT=99350, X 

// DEB= (RECFM=F,BLKSIZE=80) 



The new system residence volume is 23 volume whose serial number is 
SYSTEM. The renamed SYS1. PARMLIB will be called SYS1 .TEMPPARM. 



//MOVE JOB 

//STEP1 EXEC PGM=IEHPROGM -RENAME- 

//SYSPRINT DD SYSOUT=A 

//NEWRES DD DNIT= 23 1 4^ VOLO ME=SER=S YSTE M, DI SP=OLD 

//SYSIN DD * 

RENAME DSNAME=SYS1„PARMLIB, X 

VOL=231it=SYSTEM 

NEWNAME=SYS1 .TEMPPARM 

/* 

//STEP2 EXEC PGM=IEFBRia -REALLOCATE- 

//PARMLIB DD DS NAME=S YS 1, PARMLI B, X 

// VOLUME=C*RETAIN,SER=SYSTEM) , X 

// 
// 
// 
// 
/* 

//STEP3 
//SYSPRINT 
//SYSUT1 
// 

//SYSUT2 
//SYSIN 
COPY 

/* 

//STEP 4 
//SYSPRINT 
//NEWRES 
//SYSIN 



/* 
// 





UNIT=2314, DISP=(,KEEP) , 


X 




SPACE = TRK, (8,, 3) ,<,CONTIG) , 


X 




LABEL=EXPDT=99 350^ 


X 




DCB= (RECFM=F,BLKSIZE=80) 




EX EC 


PGM=IEBCOPY -COPY" 




DD 


SYSOUT=A 




DD 


DSNAME=SYS 1. TEMPPARM ,DISP=OLD 


X 




0NIT=231 4^ VOL=SER= SYSTEM 




DD 


DSNAME=SYS 1. P ARMLI B, DISP=OLD 




DD 


* 






INDD=SYSUT 1,0UTDD=SysaT2 




EX EC 


PGM=IEHPROGM -SCRATCH- 




DD 


SYSOUT^A 




DD 


0NIT=231 ^4, VOLUME=SER=SYSTEM,DI SP 


=OLD 


DD 


* 




SCRATCH 


DSNAME=SYS 1, TEMPPARM, 


X 




VOL=2314=S YSTEM,PDRGE 
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THE SPECIAL REAL-TIME OPERATING SYSTEM SYSGEN MACROS 



The Special Real Time Operating System SYSGEN macros fall into two 
categories: configuration and software. The following pages define 
the SYSGEN macros and list the calling sequence for each. 



CONFIGURATION CUSTOMER DIEFINTION DATA SET MACROS 



CONFIGH 



This macro defines configuration hierarchy. CONFIGK must be the first 
macro in each member of a configuration data set. For a Special Real 
Time Operating System only, it is not needed, and neither is the 
configuration data set. For a system with Display Management, it 
becomes the header macro for configuration information for the CPU it 
references. 



symbol 



CONFIGH 



CPU=S 3 70xx,LEVEL= integer 



CPU 



Must be of the form S370xx, where xx is a value between 01 and 99. 
For a system with the Special Real Time Operating System or the Special 
Real Time Operating System and Display Management, xx can be any value 
between 01 and 99. 



LEVEL 



Is a number between 01 and 99 which specifies at what level in tht 
hierarchy this CPU occurs. A 1 indicates the top (highest) level. 
The value of this parameter increases by 1 each time a lower-level 
CPU is encountered. 

The name of the configuration data set member containing the above 
macro must be the same as the CPU= parameter. 

For a Special Real Time Operating System only, no other macros follow 
the CONFIGH macro if it is used. For a system with Display Management, 
DEFDEV macros follow the CONFIGH to define each display unit. , Refer 
to the Display Management Description and Operations Man ual for a 
description of this macro. 



SOFTWARE CUSTOMER DEFINITION DATA SET MACROS 

This section defines the various macros that can be placed in the 
members of a software options data set for the Special Real Time 
Operating System portion of a system generation. The name chosen for 
a member of the software option data set should be the same name used 
for the corresponding member of the configuration data set. 

The macros defined below may appear in any order, except that the GENEMS 
macro must be last. All statements following the last continuation 
card of the GENEMS macro are ignored; as such, an assembler END 
statement is not required. 

All of the macros are optional except the VS and GENEMS macro, which 
are required. 
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vs 

Defines information relating to the customer's VS system. 




MCS= (integer , [ , integer j / • • • / integer^] ) 
,DESC=integer 

/SVCNO= (value ^ ,value 3 .value3) 
|^,APNDG= (value ^ , valuej ) J 

,NUCNUM= { character }J 
j^,RAM=xx 

] 



NO 

,CLOCKCP= j YES 



10 



PTIME= j number 



TIMEEXT=nuinber 



TIMERAT= se 



jconds I 



,GETWAS= (size , number [ , size , number , . . . ] ) j 

( YES 



NO 

,TWOPART= ) YES 



DIRSVC= NO 



MCS 

Is a list of integers, each with a value of 1 to 16, indicating which 
console routing coclss are to be used by WTOs and RTORs issued within 
the Special Real Time Operating System. 

DESC 

Is a number from 1 to 9 indicating which descriptor codes are to be 
used by WTOs or WTORs issued within the Special Real Time Operating 
System . 

SVC NO 

Is three decimal integers, in the range of 200 to 255, indicating 
which user SVC members the customer has provided for the Special Real 
Time Operating System to use. The numbers are stated in Type I, Type 
II, Type IV order. 

APNDG 

Is reguired only if System/370 Energy Management System is being 
generated. It specifies the last two characters of the name to be 
used by System/370 Energy Management System for its I/O appendages 
and must meet the rules for user I/O appendages described in the 
publication QS/VS1 D at a Manageme nt for Systems Programmer, GC28-0631. 



CLOCKCP 

If YES is specified, the optional PTIME use of ^he System/370 clock 
comparator feature is selected. 

The CPU upon which the generated Special Real Time Operating System 
will be executed must have the clock comparator feature. The 0S/VS1 
system must be generated to not use the clock comparator feature. 
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NOCNUM 

Is an alphameric character that specifies the eighth character of the 
0S/VS1 nucleus name to be created by generating the Special Real Time 
Operating System. IEANUC01 is always used as input to the Special 
Real Time Operating System generation. This parameter allows the 
output (modified) nucleus to be given a different member name. If 
NUCNUM is not specified, the resultant nucleus will have the name 
IEAN0C01 . 

RAM 

Specifies the seventh and eighth characters of the member to be created 
in SYS1 . PARKLIB, which will contain a list of resident reentrant 
routines after the Special Real Time Operating System generation is 
completed. If this parameter is omitted, no list is created. If the 
data set specified in the LMDSET parameter of the GENEMS macro is 
concatenated with SYS1.LINKLIB via the LNKLSTOO member of SYS1.PARMLIB, 
this RAM list member can be used to place the reentrant module of the 
Special Real Time Operating System (and Display Management and 
System/370 Energy Management System, if selected) in the link pack 
area. 

PTIME 

Specifies the time interval minimum value and basic cycle interval of 
PTIME. The default value is ten 1 O-millisecond units (100 ras) . If 
a different Interval is desired, it must be specified as a number of 
10-millisecond units. 

GETWAS 

Specifies the default sizes and number of blocks of each size to be 
reserved by GETWA at the Special Real Time Operating Systeot 
initialization. The sizes must be specified in ascending sequence. 
It may be overridden at the Special Real Time Operating System 
initialization time. 

The maximum number of sizes is 3 2. The maximum size allowed is 30720 
bytes. The maximum number of blocks of a given size is 4095. Sizes 
greater than 2K must be defined as multiples of 2K. 

Note: A GETWA space of sufficient size to satisfy the requirements of 

all Special Real Time Operating System programs must be provided. 
Failure to define sufficient GETWA space during system generation 
on the GETWAS parameter of the VS macro or on the GETHA statement 
in the SYSINIT input stream will result in the termination of 
the realtime job with a user 46 ABEND code. The Special Real 
Time Operating System routines require that blocks of at least 
1024 bytes be defined. 

TIMEEXT 

Specifies on which external signal line (2-7) a periodic time pulse 
is available. This pulse is used to correct for long-term drift in 
the Systea/370 TOD clock. Its omission indicates that no time sync 
pulses are available. 

TIMERAT 

Specifies the period (in seconds) at which the periodic time pulse 
will occur. The default value is 60. 

TWOPART 

If YES is specified, a twu- parti tion operation will be made available 
in the Special Real Time Operating System. If no (default) is 
specified, a two- partition operation will not be available. A 
two- partition operation should not be selected unless it is needed as 
it increases the size of the pageable nucleus- 
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DIRSVC 

This parameter indicates hoti the Special Real Time operating System 
macros which issue SVCs are to be expanded when the DCVTR and DCVTLOC 
parameters are not supplied. It applies only to the usage of the 
Special Real Time Operating System macros by user programs. The 
Special Real Time Operating System programs are required to use the 
DCVTR/ DCVTLOC parameter or to be assembled at SYSGEN time. If yes 
(default) is specified, the macro expansion will issue the correct 
SVC number inline. This ties the assembly of the user programs to 
the SVC numbers used at that installation. If no is specified, the 
macro will expand 6 load instructions to obtain the XCVT and then 
execute the SVC from the XCVT. Thus, the user program is not tied to 
the SVC numbers. 
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FAILPSr 



This macro causes the Fai lover/Re start facility to be included in the 
system. Also, it optionally includes the continuous monitor or PROBE 
and the Computer Status Panel. 



[ -.ymbol] 



FAILRST 



CONTMON 



i NO n r j 1 11 

= I YES IJ [,CONTINT= | number M 
CONTADL= (name^ j^fname^^ • . . ,naine^J)J 

NO n r j LOW 4 ( 1 

j HIGH4jJ 



,PROBE= I YES| J 



,EQUIPSW= j number 



,EQUIPDY=number 



NO 

,RESET= ) number 



m (1 r 

mberJJ [, 



, STATUS P 

,FAILEXT=(number [ , static line] ), 



NO 

,CMCKPRB= J YES 



0 



CONTMON 

Causes the continuous monitor facility to be included in the system 
if YES is specified. 

CONTINT 

Specifies the period (in seconds) at which the continuous monitor is 
to check the operation of the online CPU ana report to the backup CPU 
(if PROBE is selected) . 

CONTADL 

Specifies the names of additional 2-byte virtual storage resident data 
base items which the continuous monitor is to periodically check. 
This is in addition to locations it implicitly checks within the 
Special Real Time Operating System. 

PROBE 

Causes the PROBE function to be generated if YES is specified. 
CONTMON^YES is required. The period at which the PROBE function 
expects to be transmitted to by the continuous monitor is specified 
in the CONTINT parameter. 

PROBIT 

Specifies whether the low-order (4-7) or high-order (0-3) bits of the 
direct control static data lines are to be used for the continuous 
monitor to send signals to the PROBE. 

EQUIPSW 

Specifies to which direct control signal-out line (0-7) the remote 

29 14 switch is attached. This option This option requires PROBE=YES. 

EQUIPDY 

Indicates how long (in milliseconds) the PROBE function is to delay 
after switching the 2914 before either IPLing the Failover/Restart 
data set or returning to allow the realtime job to continue. The 
delay is to allow the 29 14 to complete the switch. 
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RESET 



If specified, indicates on which direct control signal-out line (0-7) 
a signal can be sent to alloif one CPD to system reset the other CPU. 
This option requires PROBE=YES. 

STATUS? 

If specified, indicates that the continuous monitor and/or PROBE is 
to support the Computer Status Panel. CONTMON=YES is required. 

LTS 

Is required if STATU SP=YES. Two values are required if PROBE=NO, and 
four values if PROBE=IES. The first (or only) two values indicate 
which direct control signal-out line (0-7) is to be used to illuminate 
the Online light and the Ready light. The second two values indicate 
which bits on the direct control static data lines (0-7) are used to 
illuminate the Failover Recommend and Computer Selected for Failover 
lights, 

FAILEXT 

If specified, the first parameter indicates which external signal line 
(2-7) will be used to indicate the Failover Confirmed Interrupt of 
the Computer Status Panel. Requires PROBE=yES and STATOSP=yES- The 
second parameter (optional) indicates which static signal line is used 
to verify that the Failover Confirmed External Interrupt is to be 
honored. This line must be 1 or the interrupt is ignored, 

CMCKPRB 

This parameter indicates if the PROBE function (backup CPU) is to be 
checked by the continuous monitor (online CPU). The PROBE (if 
selected) always checks the continuous monitor. If the continuous 
monitor detects that the PROBE is no longer running, it issues a 
message and continues operation. 

Warning : If this option is chosen, the PROBE also writes and therefore 
it is possible to start a PROBE function in each CPU and 
have neither PROBE recommend failover as each PROBE is 
receiving data on the static data lines from the other PROBE. 
This is not possible without this option as the PROBE 
attempts only to "read" from the continuous monitor but 
never write to it. 
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DUPDISK 



Includes duplicate disk data set support in the Special Real Time 
0 pe ra t i ng S ys te m . 



[symbol ] 



DUPDISK 
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DBASE 
Specifies 



customer arrays to be generated. 



[symbol] j DBA SE 



USER ARR = ( name ^ , namCj , . ■ ■ , name ^ ) 



OSERAER 

Specifies the member names of customer-supplied data base arrays, in 
source format, which are to be processed through the offline utility 
during Stage II SYSGEN. The data set containing the array definitions 
is defined in the DBDSET parameter of the GENEMS macro. 
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LOG 

Includes data base logging in the Special Real Time Operating System. 



[ symbol ] 



LOG 



LOGFREQ" (value .value .value) 



LOGFREQ 

Specifies the loggiag period in seconds corresponding to LOGFREQ values 
of ^, 2, and 3 in the ARRAY macro. All three values are required. 
The values must be in ascending sequence. 
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PLISOB 



Indicates that PL/I structares and libreury routines are to be included 
for the Special Real Time Operating System services. If Display 
Management and/or System/370 Energy Management System are being 
generated also, structures and library routines are included for their 
services as well. These routines can be used with PL/I P, the PL/I 
Optimizing Compiler and the PL/I Checkout Compiler. 



[ symbol ] 



PLISUB 
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FOESOB 



Indicates that FORTRAN library routines are to be included for the 
Special Real Time Operating System services. If Display Management 
and/or System/370 Energy Management System is being generated also, 
library routines are included for their services as well. These 
routines can be used with the FORTRAN G and H compilers. 



[ symbol ] 



F0RSU6 
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MSGRC 

Defines devices for routing codes for system messages. 



I^symbol j 



MSGRC 



RC=code 



,DEV= 



,ALTRC 



.11 

1 code 



P 



SYSCONS 

(OSDEVICE , DDNAME=naine) 

(DISPLAY, ACCESSA=name [,FUNCA=naine] ) 

( PATCH, EP=name) 



RC 

Indicates which routing code is being fully or partially defined. 
Valid codes are numeric in the range of 1 to 255. Codes 1 through 9 
are reserved for the Special Real Time Operating System, The customer 
should define the destination for codes 1 through 9 for the Special 
Real Time Operating System messages as well as his own from 10 to 255. 
A routing code can be defined to go to multiple devices by including 
multiple MSGRC macros with the same RC specification. The MSGRC macros 
must be in ascending routing code order. Code 1 will always go to 
the system console (in addition to any other defined devices). 

ALTEC 

Indicates an alternate routing code to use if the device defined is 
not available. 

DEV 

Indicates which device to output the message. 
SYSCONS 

Indicates that a WTO will be issued, 
OSDEV ICE 

Indicates that a QSAM POT will be done to the DDname specified. 
DISPLAY 

Is valid only in systems with Display Management. The message will 
be written to the system message zone using the indicated access area 
and function area codes, if supplied, 

PATCH 

Indicates that the message is to be passed to a Special Real Time 
Operating System independent task at the entry point indicated. The 
task name is the same as the entry point name. 

ACCESSA 

Indicates the Display Management access area associated with a DISPLAY 
routing code. 

FUKCA 

Indicates the Display Management function area associated with a 
DISPLAY routing code. 
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IMP 



Indicates input message processing commands in addition to those defined 
as part of the Special Real Time Operating System. There is one IMP 
macro per code. 



[ symbol ] 



IMP 



CODE=name , TASK=name , LM=name , 



[, ID= jnumber j] [,PARAM= |val^ [, val2 / . . . ''^^^n])] 



CODE 

Is the command which the Input Message Processor is to recognize; it 
contains a maximum of eight characters. By specifying a command 
implicitly defined by the Special Real Time Operating System the 
customer can re-define these codes. 

TASK 

Is the name of the task which is to be PATCHed as a result of the 
command being entered. 

LH 

Is the load module name which is to be PATCHed, 
ID 

Is the ID field to be passed to the PATCHed task. 
PA RAM 

Indicates the conversion codes of positional parameters that will be 
passed to the task. Each value is of the form Tl, where T can be 
C (character) , X(hexadecimal) , or F (fixed point decimal); 1 represents 
the length of the area into which the data is converted; I can be any 
values from 1 to 2 55. 
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DATA SET 



Indicates location of noncataloged 0S/VS1 data set. 
set is cataloged, this macro need not be specified. 



If the 0S/VS1 da 



[symbol] 



DATASET 



name, VOL= (serial.type) 



n ame 

Is a positional parameter that indicates for which 0S/VS1 data set 
location information is being given. Valid values are: 

NUCLEUS 
SVCLIB 
M ACL IB 
FARM LIB 
TELCMLIB 



VOL 

Indicates the volume serial number and device type upon which the da 
set in question resides, e.g., VOL=(TST3U6, SYSDA) . 
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GENEMS 

Generatfes the Special Real Time Operating System, 



[symbol] 



GENEMS 



( 370 
CPU- ( S370XX 

j 9E 
,ASMPRT>= I OFF 



,LKPRT= 



,JOBCTL 

,OBJDSET=name 



J [,ASMBLR= (h } ] 

( Jx^''Fi][,LIST] )] 

= ( { jobclass }J [I, outclass Ij job acctj 
,OBJVOL= (serial, type) ] 



step acct 



]) 



,LMDSET=name 
,MACDSET=name 
[,DBD ] 

[,DISDSET=nanie] 
, ARRDSET=name 
, DB 1 DSET=name 
, DB2DSET=naine 
[<DB3DSET=name] 

, DB4DSET=narae 
[,DB5DSET=namel 
( , PLIUSET=name] 
[ , PLSDSET=nanie J 
( ,FORDSET=name] 
[,0S2DSET=namel 



,LMVOL=(serial,type) ] 
,MACVOL= (serial , type) ] 
,DBVOL= (serial , type) ) 
,DISVOL= (serial , type) ] 
,ARRVOL= (serial , type) 3 
,DB1V0L= (serial, type) ] 
,DB2V0L (serial , type) ] 
,DB3V0L= (serial , type) ] 
, DB4V0L= (serial , type) ] 
,DB5V0L= (serial, type)3 
,PLIVOL= (serial, type) ] 
,PLSVOL= (serial , type) ] 
,FORVOL= (serial , type) ] 
, 0S2V0L= (serial, type)] 
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CPU 

May be specified as either S370 or S370xx, vhere xx is equal to the 
ID assigned to this CPO in the CONFIGH macro CPU keyword. 

ASMPET 

Is indicated if assembly listings are to be produced during Stage II. 
The default is OFF. 

ASMBLE 

Indicates which assembler is to be used during Stage II. The default 
is the 0S/VS1 Assembler (F) . The Assembler H Program Product, 
5734-AS1 , may ba specified. If the H assembler is specified, it is 
assumed that it has been installed using the default DD names. 

LKPRT 

Indicates which linkage editor listing options are desired. 
JOBCTL 

Indicates values for job and SYSOOT classes and accounting information 
for the Stage II job stream. 

jobclass 

Specifies the value to be used in the CLASS parameter of the generated 
job card. 

outclass 

Specifies the output class to be used in the SYSOUT parameter on DD 
cards and the MS(3CLASS parameter on the JOB card. 

job acct 

Is the information to be reproduced in the accounting field of the 
JOB card. 

step acct 

Is step accounting information to be reproduced in the ACCT parameter 
of each EXEC card. 

The following table summarizes the use of each XXXDSET parameter. The 
value specified is in each case the name of a data set allocated and 
named by the installing installation. The corresponding XXXVOL 
parameter is used to indicate the location of the data set, e.g., 
XXXVOL= (TSTBUe^SYSDA) , if it is not cataloged. All of the data sets 
must be disk resident, and all are partitioned except the DB2DSET which 
is direct organization and the 0S2DSET which is sequential or the member 
of a partitioned data set. 
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Parameter 


Requi red 


Contents 


DCB Info 


OBJDSET 


Yes 


Output of Language 
Translator During 
Stage XI 


LRECL=80 , RECFM=FB , 
BLKSIZE=XXX ^ 


LMDSET 


Yes 


Load Modules for real 
Time Execution 


RECFM=U , ELKS I ZE=XXX ^' ® 


MACDSET 


Yes 


Macros Generated 
During Stage II and 
For Customer Use 


LRECL=80 , RECFM=FB , 
BLKSIZE=XXX^ 


DUUSET 


If USERARR PARM in 
DBASE Macro is Used 


Cus tomer - Def ined Data 
Base Arrays 


LRECL=80,RECFM=FB, 
BLKSIZE=XXX^ 


DISDSET 


If UISM in System 
and iser Displays 
De f 1 :ied 


Cus tomer- Defined 
Display Definition 


LR£CL=80 , RECFM=FB , 
BLKSIZE=XXX^ 


ARRDSLT 


Yes 


Arrays Generated 
During SYSGEN 


LR£CL=80 , RECFM=FB , 
BLKSIZE=XXX^ 


UblUSET 


Yes 


Data Base Arrays 


RECFM=U,BLKSIZE=XXX^ 


Db2DSET 


Yes 


Data Base Arrays 


RECFM-U,BLKSIZE=XXX^,DSORG=DA 


DB3DSET 


If DISM in Sy.st.em 


Displays 


RECFM=U,BLKSIZE=XXX2 


Uts4DSET 


Yes 


Messages 


RECFM=U,BLKSIZE=29 2 


DB5DSET 


If DISM m System 


Displays 


RECFM=U , BLKS I ZE=XXX ^ 


PLIUSET 


If PLISUB Macro 


PL,'I Library Routines 


RECFM=U,BLKSIZE=XXX'^' ^ 


PLSDSET 


If PLISUB Macro 
Specified 


PL/I Structures 


BLKSIZE=XXX^' ^ 
LRECL=80 ,RECFM=FB, 

BLKSIZE=XXX^' ^ 


FORDiiET 


If FORSUB Macro 
Spcci f iod 


FORTRAN Library 
Routines 


RECFM=U ,BLKSIZE=XXX'*' ^ 


0S2USET 


If installing in 
Hel 3.0 or later 


OS/VS Stage II 
SYSGEN job stream 


RECFM=FB,LRECL=80 , 



Maxipiuiii of 3200 due to OS/VS Linkage Editor restriction. 

2 

Value of at least half track length recommended. 

3 

Should liave same BLKSIZE as installations SYSl.MACLIB. 

4 

May be same data set as LMDSET. 
^If PL/IF 13 to be used, BLKSIZE cannot exceed 400. 
^A value equal to SYS1.LINKLIB recommended. Minimum of 7294. 

Figure 3-4. XXXDSET Parameter Values 
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SYSTEM INITIALIZATION 



The Special Real Time Operating System executes as a job step under 
control of 0S/VS1. The job is started initially through standard 0S/VS1 
Job Control (JCL) statements with the EXEC card specifying PGM=DPPINIT. 
The JCL defines to the Special Real Time Operating System the data sets 
which have been created by the offline utility and the Special Real 
Time Operating System SYSGEN procedures. The JCL also defines the 
devices such as display and data acquisition, which are to be used by 
the online routines. Control statements for the initialization of 
subsystems are defined to the Special Real Time Operating System through 
the //SYSINIT DD card. Also included in the SYSINIT input stream are 
certain Special Real Time Operating System parameters that can override 
SYSGENed values. 

The Special Real Time Operating System initialization consists of three 
processing phases: card read, basic initialization, and subsystem 
initialization, as shown in Figure 3-5. 



Basic Initialization 



CALL 
EP = DPPINITO 



ATTACH EP = DPPINIT1 
XCTL EP = DPPTSMON 



Card Read 



DPPINITO 



Subsystem Initialization 



DPPINIT DPPINIT1 

Figure 3-5. The Special Real Time Operating System Initialization 



Program DPPINIT gains 
DPPINITO, the control 
statements from the i 
and builds a chain of 
with one block built 
found in the input st 
is returned to DPPINI 
control block chain, 
blocks and when this 
XCTLs to DPPTSMON. D 
chain built by DPPINI 
PATCHes as specified 
the control statement 



control from OS and imm 

statement read routine, 
nput stream specified by 

control blocks to repre 
for each PATCH, WAIT, RE 
ream. When End-of-File 
T, with register 1 conta 

DPPINIT initializes the 
is completed, attaches p 
PPINIT passes the origin 
TO to DPPINIT1, which pr 
by the user in the input 
s that are valid as inpu 



ediately CALLs program 
DPPINITO reads control 

the DD card named SYSINIT, 
sent the input stream, 
START, and ABEND card 
(EOF) is reached, control 
ining the origin of the 

task management control 
rogram DPPINIT1, then 

of the control block 
ocesses and issues the 

stream. Figure 3-6 shows 
t to initialization. 



The control statement input stream defines the sequence of events that 
is to occur during subsystem initialization. The stream is a series 
of card image input statements coded similar to assembler language 
macros. The rules for continuation of control statements are the same 
as those for continuation of assembler language macro calls. 

A control statement consists of a NAME field which is optional, an 
OPERATION field, which is required, and operands. The maximum number 
of operand characters is 255. There is no limit on the number of 
continuation statements, as the limiting factor is the number of 
characters of operands. 
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NAME 



OPERATION 



label 



label 
label 

label 
label 

label 
label 

label 
label 
label 
label 
label 
label 
* 

label 



PATCH 



WAIT 



QH 



STAEX 
RESTART 

TCB 

GETWA 

CBGET 

ABEND 

MASTER 

SLAVE 

conunent 

DBREF 



OPERANDS 



EP=name 
[, ID=n] 



TASK=name 



,PRTY 



^ [ JOBSTEP-n n 
I (taskname ,n)J j 



, PARAM= 



C ' characters ' 

X ' hexadecimal digits' 

F' decimal number' 



■})] 



label 



,QL=- 



255 



,SEQ= 



YES 



,HOLD= 



YES 



,PATCH= 



NO 



number, QH=(nanie2,. . . .name^) , PRTY= 

EXIT=name, IJ4=(nameT .name. .name ) 

1 c n 



JOBSTEP-5 - 
JOBSTEP-n 



, WRITE ] (, PROBE ) 
|, NOWRITE j |, NOPROBE j 

number 

(number , value , ... ) 
number 
t ,DUMP 

SLAVE= jobname 
MASTER= jobname 
comment 



YES 
NO 



, CMON 
,NOCMON 



, CANCEL 
,NOCANCEL 



Figure 3-6, Control Statement Input Stream 
PATCH 

Causes the creation of a task as defined by the PATCH macro, 
PATCH control statement operands are: 



The 



EP=Dame 

Is the name, one to eight characters in length, of the program to be 
PATCHed. EP= must be specified. The card read routine checks that 
the name does not exceed eight characters, but does no other validity 
checking on the name. This applies to any othar operaad that requires 
name, taskname, or jobname. 

TASK=name 

Is the name, one to eight characters in length, to be given to the 
task created by this patch. 

QL=n 

Is the maximum number of work queue entries to be given to the task. 
The number (n) must be a decimal number from 0 to 2 55, with a default 
value of 1. 
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lD=n 

Hust be a decimal number from 0 to 255 which Mill be passed to the 
PATCHed program. The default is 0, and 255 has special meaning a^^ 
specified in the PATCH macro documentation. 

PRTY= 

Is used to determine the priority of the PATCHed task. Hhen JOBSTEP- n 
is coded, the PATCHed task's priority is calculated by subtracting 
the value "n" from the highest priority available to users, which is 
the job step task (DPPTSHON) priority minus three. Value n must be 
a decimal number from 0 to 255. Hhen (taskname,n} is coded, the task 
is given a priority of the task specified in taskname minus the value 
n. In either case, value n is a decimal value from 0 to 255. There 
is no default, and value n must be supplied. If PRTY is not 
specified, the task will have the priority of the PATCHor (in this 
case the highest possible user priority). 

PARAH^ 

Specifies the parameters to be passed to the PATCHed program. There 
are three types of data which can be coded: 

C« charact ers* 

Cause a character string to be passed. The single quote character 
(') is not allowed in the character string. 

X * hexadecimal digits* 
Cause hexadecimal data to be passed and must be valid hexadecimal 
digits 0-9 or A-F. 

F'decimal number* 
Causes a fullword value to be passed and must be a signed uecimal 
number from 0 to 2 3^ . A conversion will be done by the 
initialization program. 

WAIT 

Causes initialization to wait for the completion of a specified task^, 
the task being the one PATCHed by the control statement with the same 
name as the operand "label," The wait is only for the task to return 
(i.e., the processing of the work queue that is created as a result 
of the patch card to be completed) and has no relationship to any work: 
that may be created by that task via PATCHes or other means. 

QP 

Causes the cteation of a queue processor identified by the number 
parameter and a logical sequence for processing queue holders defined 
by the QH parameter. The number and QH parameters are required. The 
QP control statement operands are defined as follows: 

number 

Is a numberic value from 0 to 99 used to uniquely identify a queue 
processor. If more than one QP statement is found in the input stream 
with the same number, initialization will be terminated. This queue 
processor may be referenced in subsequent QS commands by this number. 
An internal TCBX (task) name will be created for each QP in the format 
****QPnn, where nn is the number specified here. PATCHes specifying 
the queue processor name as the task name will be rejected and a 
condition code will be returned to the user. 

QH=name 

Defines the names of from 1 to 21 queue holders for which work is to 
be processed by this queue processor. Any one queue holder name may 
be specified on up to 21 QP statements. The specified queue holder 
names are treated on a priority basis where work from the queue holder 
appearing first in the list will be processed first. This queue 
processor will select work from the first queue holder specified 
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until all work in the queue holder has been selected before selecting 
work from the second queue holder specified. Each queue holder nanie 
specified on a QP statement must be defined by a QH statement. 

PRTY = 

Is an optional parameter used to determine the dispatching priority 
of this queue processor task. When JOBSTEP-n is coded the queue 
processor task's priority is calculated by subtracting the value, n, 
from the highest priority available to users, which is the jobstep 
task (DPPTSMOK) priority minus three. The value, n, is a decimal 
number from 0 to 255. If PRTY is not specified, the queue processor 
task will be assigned a priority of JOBSTEP-5 (i.e., the job step 
task's priority minus 8). 

HOLD = 

Is an optional parameter that can be used (HOLD=YES) to inhibit this 
queue processor from selecting work from any queue holder until 
released by a subsequent QS command specifying r xx,QS,QPnn,REL where 
nn is the number specified on this QP statement (or the equivalent 
using the ALL or ALL QP operands) - If HOLD=YES is not specified, 
theis queue processor will be immediately available for normal 
processing. 

QH 

Defines the queue holders and identifies each by the name parameter. 
The name parameter is required. The QH control statement operands 
are defined as follows: 

name 

Is a 1 to 8 character name used to uniquely identify a queue holder. 
If more than one QH statement is found in the input stream with the 
same name, initialization will be terminated. This queue holder may 
be referenced in subsequent QS commands by this name. Work requests 
for this queue holder must specify this name as the task name on the 
PATCH Hnacro call. 

QL = 

Is an optional parameter that is used to limit maximum number of work 
queue entries to be given to this queue holder. This number, n, must 
be a decimal number from 1 to 2 55. The default queue length is 255. 

SEQ= 

Is an optional parameter that can be used (SEQ=YES) to request that 
work queued to this queue holder be processed sequentially (i.e., 
whenever work has been selected from this queue holder by a queue 
processor, no other queue processor may select work from this queue 
holder until that work has been completed) until altered by a 
subsequent QS command specifying r xx#QS,name,NONSEQ where "name" is 
the name specified on this QH statement. If SEQ=YES is not specified, 
work from this queue holder may be processed simultaneously by all 
queue processors which are eligible to process work from it. 

HOLD = 

Is an optional parameter that can be used (HOLD=YES) to prohibit any 
queue processor from selecting work from this queue holder until 
released by a subsequent QS command specifying r xx,QS, name , PEL where 
"name" is the name specified on this QH statement. If HOLD=YES is 
not specified, this queue holder will be immediately available for 
normal processing. 

PATCH= 

Is an optional parameter that can be used (PATCHING) to cause all 
PA.'CHes to this queue holder to be rejected and a condition code to 
be returned to the user until altered by a subsequent QS command 
specifying r xx,QS, name, PATCH where "name" is the name specified on 
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this QH statement- If PATCH=NO is not specified, this queue holder 
will accept all valid PATCHes. 



STAEX 

Is used to specify an exit routine load module that will be given 
control when one of the load modules specified on this STAEX statement 
abends. Multiple STAEX statements may be included in the SYSINIT 
input stream to define additional exit routine and/or load module 
names- However, if a particular load module name is specified on more 
than one STAEX statement, the exit routine defined on the last STAEX 
statement in the input stream that references this load module name 
is the exit routine that will be given control in the event of an 
abend of that load module. Unless the exit routine requests that the 
STAE processing be bypassed, the STAE options as defined 
by the STAE ISP command (i.e., DOMP, NODUMP, etCo) will remain in 
effect. 

EXIT= 

Is the name of an exit routine load module to be given control through 
standard linkage conventions during STAE processing. The same 
exit routine may be specified on two or more STAEX statements- This 
routine will be given control while in STAE processing and standard 
limitations for STAE routine apply (i.e., a STAE macro cannot be 
issued, etc-). On entry to the exit routines, registers 0, 1, 13, 1U 
and 15 will contain the values as defined by 0S/VS1 STAE interface 
routines. Register 2 will contain the address of the QP TCBX- The 
exit routine must specify, by a return code in register 15, one of 
the following: 

Re turn Cod e Action to be Taken 

Zero Continue STAE processing as defined by 

the STAE IMP command (i.e., DOMP, NODUMP, etc.). 

Positive Value Bypass STAE processing and return to the 

0S/VS1 ABEND processing routine with registers 
0, 1, and 15 as returned by the exit routine. 
This will allow the user to schedule a retry 
routine- 
Negative 1 Bypass STAE processing, zero register 15, 
and return to the 0S/VS1 ABEND processing 
routine. Abnormal termination will continue. 

If the load module specified is not available on the JOBLIB/STEPLIB 
data sets at initialization time, initialization will be terminated. 

LM= 

Is the name of one or more user load modules for which the specified 
exit routine is to be given control in the event of an abend of that 
load module. 

RESTART 

The operands are not positional and may be coded in any sequence; 
however, if the statement is to be in the input stream, at least one 
of the operands must be used. 

WRITE or NOW RITE specifies whether or not the failover data set is to 
be written- 

PROBE causes the PROBE function to be PATCHed after the RESTART 
processing whether or not a failover data set is written- NOPROBE 
causes no PATCH to the PROBE. If both PROBE and CMON are requested, 
the PROBE is PATCHed first. 
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CMON causes the continuous monitor function to be PATCHedp 

NOCMON does not PATCH the continuous monitor « 

CANCEL causes the job step task to ABEND with a user code 45 
immediately after the RESTART processing. The CANCEL function will 
occur prior to the PATCH to PROBE or continuous monitor. 

NOCANCEL does not ABEND the jobstep and normal processing continues, 

TCB 

Causes a change in the number of advance TCBs to be obtained by 
initialization- The number (0-99) overrides the value specified at 
SYSGEN tiffie„ If more than one TCB statement is found, the value used 
will be the value on the last statement. 

GETWA 

Overrides the SYSGENed values for GETHA sizes. The values must be in 
parentheses and be paired (i.e^, number, value) , The maximum number 
of pairs is 32, where number represents the number of blocks, and 
value represents the size of the GETWA blocks; i.e., (5,72) requests 
5 blocks of 72 bytes each. The maximum size of number is 4095, and 
the maximum size of value is 30710 bytes. If more than one GETWA 
statement is found in the input stream, the values used for 
initialization are the values from the last GETWA statement 
encountered. If two parameters request the same size, the second 
request is unusable. Sizes greater than 2K must be 2K multiples. The 
Special Real Time Operating System uses GETHA space in blocks up to 
1024 bytes. If the GETWA statement is used, it liust include blocks 
of 1024 bytes or larger. 

CBGET 

Causes the amount of CBGET (the Special Real Time Operating System 
Control Block) storage to be varied. The initialization default value 
is the number of TCBs multiplied by TCBXLNTH, rounded to 2K plus 6K. 
The value, specified by number, overrides the initialization default 
value and is a decimal number from 1 to 99 representing the number of 
2K blocks of storage to get for CBGET core. For example, 10 would 
get 20K of CBGET storage. If more than one CBGET statement is in the 
input stream, the value used is the value from the last statement 
encountered. A CBGET 0 statement will cause initialization to use a 
default value for CBGET storage. This would be the same as if no 
CBGET statements were in the input stream. 

ABEND 

Is a control statement used in a testing environment. When an ABEND 
card is processed, the job step will be ABENDed with a user 22 ABEND 
after a time specified by t, where t is the number of seconds from 1 
to 999. The default value for t is 30 seconds. A dump can be taken 
by coding DUMP, and the default is no dump. Control statements that 
follow the ABEND statement in the input stream will never be processed, 
as the ABEND causes a STIMER WAIT followed by the user ABEND. 

MASTER 

Is a statement used to designate this Special Real Time Operating System 
initialization as a MASTER partition for two- partition operation. 
SLAVE= jobname specifies the jobname of the SLAVE partition, 

SLAVE 

Indicates this initialization is for a SLAVE partition in tw o- partition 
operation- The MASTER- jobna me operand specifies the jobname of the 
MASTER partition. Only one MASTER or SLAVE card is allowed in an 
input stream, and the jobname on the operand must be unique in the 
system , 
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Is a comment statement. No continuations are allowed on comment 
statements and there is no limit to the number of comment statements 
in an input stream. Comments do not affect the initialization 
sequence, but will appear in the listing of control statements. 

DBREF 

Indicates to data base logging that the data base should be refreshed 
during a normal start operation. That is, the most recently logged 
copy is to be used. The operand NO must be coded to stop data base 
refresh. The absence of a DBREF statement is the same as a DBREF YES. 
A DBREF NO Statement in the input stream takes precedence over any 
DBREF YES Statements in the same input stream. 

The card read routine reads until EOF is reached and then returns 
control to DPPINIT. All control statements are processed, and input 
statements and any diagnostic error messages are written to the data 
set specified by the SYSPRINT DD statement. If any control statements 
are in error, the run is aborted with a user 34 ABEND, and a WTO message 
is written to the console. 

The following example shows the JCL required and a typical input stream 
for the Special Real Time Operating System system initialization. 



//REAL 


JOB 


3DE501 PROGRAMMER '.CLASS 


= F 


// 


EXEC 


PGM=DPPINIT 




//STEPLIB 


DD 


DS N= AC S370 iL M 01, DI SP=S H R 




//DBINIT 


DD 


DSN=ACS370.DB1 ,DISP=SHR 




//DBINIT2 


DD 


DS N= AC S3 70 -JD B2 , D I S P= SH R 




//MSGDS 


DD 


DS N= ACSiia BU , D I S P= SH R 




//DPPFAIL 


DD 


DSN=ACS370-FALRST.DISP=OLD 


//SYSPRINT 


DD 


SYSOOT=A 




//MSGOOT 


DD 


SYSOUT=A 




//SYSUDOMP 


DD 


sysouT=A 




//SYSINIT 


DD 


* 




PI 


PATCH 


EP=PINITOO ,TASK=STARTER, 
QL=5,ID=7,PRTy=J0BSTEP-15 




P2 


PATCH 


EP=XINIT,TASK=SUBSYS1, 
QL=10,ID=1 0,PRTy=JOBSTEP- 


16 


P3 


PATCH 


EP = DBUILD, TASK = DATBAS, ID= 


2 55 


W1 


WAIT P2 






PU 


PATCH 


EP=XUSE,TASK=S0BSYS2, 
QL=5,ID=15 ,PRTY= (SDBSYSI, 
PARAM= (F'a7« ,F'52' ,X'A0B' 


5). 
) 


P5 


PATCH 
RESTART 


EP=PUSE 
WRITE 




P6 


PATCH 


EP=XREINT, TASK=MCTL, QL=1 5 
PARAM= (C'POSTWRS') 


r 


P7 


PATCH 


EP=DBRST,T ASK-DBUSE, 





PRTY=JOBST EP-2 



In this example, the JOB card is standard OS, and accounting information 
must be as required for the individual installation. The EXEC card 
must specify PGM=DPPINIT. The STEPLIB DD card points to the 
library (ies) contaiiiing the Special Real Time Operating system and user 
programs. The library name will depend upon the name given the data 
sets at SYSGEN time. The data sets required for the data base are 
pointed to by the DD cards DBINIT and DBINIT2. The online message 
handler requires the MSGDS and MSGOUT DD cards. The SYSPRINT DD card 
is required by initialization to print the input control statements. 
k SYSUDUMP or SYSABEND DD card is optional, depending on whether a dump 
is required on ABEND conditions. The SYSINIT DD card is required, and 
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it must point to the data set containing the control statements for 
the online run. 



The input control statements in the preceding example show a typical 
initialization sequence. The RESTART statement implies a wait on PATCH 
statements labeled Pi, P2 , P3 , P4 , and P5. There is also an implied 
aait on P6 before initialization is completed. The The RESTART WRITE 
makes the DPPFAIL DD card necessary- 
All programs which are to be PATCHed via a PATCH statement prior to 
the RESTART statement musj: go to termination before the restart data 
set can be written. Each program PATCHed prior to the RESTART statement 
is PATCHed with the ECB= operand. The ECB will be posted with the POST 
bit, plus the contents of register 15 at the time the PATCHed program 
returns control to the Special Real Time Operating System. If there 
is no RESTART WRITE in the input stream, there is an implied wait before 
initialization termination on all PATCHes issued with the PARAM= keyword 
coded on the PATCH statement. Any PATCH receiving a non-zero return 
code will cause the job step to abend with a user 031 ABEND code. 

PATCHes in the input stream that follow a RESTART statement do not 
imply WAIT unless the PATCH statement contains the PARAM= keyword. 
There is an implied wait on each PATCH with the PARAM= keyword that 
follows the RESTART WRITE statement. Explicit waits may be forced on 
any PATCH statement through the use of the WAIT statement. 

Opon regaining control from DPPINITO, DPPINIT initializes the task 
management control blocks. The XCVT and SCVT are initialized in subpool 
253. The MASTER and SLAVE partitions are synchronized at this point 
if the run is for two-partition operation. DPPINIT then creates the 
TMCT in subpool 253 and initializes the GETWA control blocks and GETWA 
core, and the Special Real Time Operating System control block (CBGET) 
core. After creating the advance TCBs, DPPINIT links to other Special 
Real Time Operating System initialization routines in the following 
order: 

• Duplicate Data Set Support (if SYSGENed) 

• Data Base 

• Realtime Message Handler 

• Time Management 

• Data Base Logging 

Upon completion of these routines, task management is initialized and 
ready to process PATCHes. At this time, DPPINIT attaches DDPINIT1 and 
then XCTLs to DPPTSMON. 
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Program DPPINIT1 processes the input stream and PATCHes the subsystea 
programs. A program that has been PATCHed by initialization receives 
control with pointers as shown below. 



Register 1 



XCVT 



Resource Table 



PROBL 



8-byte Resource Table 



0 


1 


2 


3 


LENGTH 


00 


ID 


FLGS 


Reserved 







8 LL 



FARM 



The PROBL contains the LENGTH, which is the length of the PROBL 
including parameter pointers. If ?ARAM= were coded on the PATCH input 
statement, there would be one word appended to the PROBL for each 
parameter being passed. The format of this word is that the high-order 
byte contains the length of parameter data, and the low-order three 
bytes contain the address of the data. 

The ID is the value coded in the ID= field of the PATCH statement. The 
FLGS are as shown below; 



FLGS 
BIT 



UNUSED 



PRE-RESTART 

INITIAL IPL 
SAME CPU AS IPL 



Through interpretation of the PROBL FLGS, programs can determine if 
they were PATCHed prior to the writing of the failover data set (bit 
7=1), if the system is being restarted (bit 6=0), or if the system has 
been failed-over to a backup CPU (bit 5=0) . 
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The following PATCH statement would cause the program named REFNAME to 
receive control with parameters as shown below. 



PI PATCH EP-REFNAME, ID=15, 

PARAM=(C'FIRST',X'FFA',F72',F-r) 



Register 



XCVT 



Resource TBL 



PROBL 



0018 00 OF 


07 


Unused 


05 


f FARM 


02 


f PARM 


04 


1 PARM 


04 


f PARM 



♦ 8-byte Resource TABL 



C6C9D9E2E2 



OFFA 



00000048 



■> FFFFFFFF 



PATCHes issued ptior to RESTART WRITE are issued with ECB= , and upon 
completion the post code is checked. MESSAGE DPP0U4I is issued for 
each PATCH prior to RESTART WRITE that is posted with a non-zero post 
code. If any ECBs have been posted non-zero, the job step will be 
ABENDed with a user 35 ABEND code just prior to the writing of the 
restart data set. 

PATCHes issued for PATCH statements following the RESTART WRITE 
statement will be issued with the ECB= keyword also, only if they are 
coded with PARAM= or have WAIT statements naming the PATCH statement. 
As prior to RESTART WRITE, the ECBs are checked for non-zero post code, 
and message DPP044I will be issued for any task being posted non-zero. 
The job step, however, will not be ABENDed due to post codes for PATCHes 
following RESTART WRITE. If there is no RESTART WRITE statement in 
the input stream, the job step will be ABENDed (user 35) for any task 
posted non-zero. 

When all the input stream control blocks have been processed, DPPINir 
frees all storage obtained, and exits from the system. At this point 
Special Real Time Operating System and subsystem initialization is 
completed . 



DDS Initialization 

The initialization of Duplicate Data Set (DDS) support is accomplished 
by including the DUPDISK macro in the Special Real Time Operating System 
SYSGEN input. This will cause the initialization to link to DDS 
initialization in the prescribed sequence. 
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DDS initialization consists of the following functions: 

1. Processing the DDS input control stream (defined by DDSCTLIN DD 
card) for DDS declarations. 

2. Initially writing (and creating if not already done) the DDSTATJS 
data set record (calculating the maximum block size for use in 
later updates to this data set) . 

3. Allocating a DDS control header table (DDSCTLHD) and one DDS 
control area (DDSCTLA) for each DDS declared (initializing these 
tables with correct values). 

4- Defining locks for each DDS declared (logically referred to as 
DDS-lock/share-ECB-chain locks) . 

5. Loading all DDS load modules (except the large and infrequently 
used modules) and saving their addresses in the DDS control 
table header. 

6. Connecting the DDS-xiontrol table header to the SCVT and each 
DDS control area to the DDS control table header. 

Detailed Explanations 

The DDS input control stream (consisting of 80-byte card images) is 
outlined in the following table: 



Name 


Opcode 


Parameters 


ddsname 

blank 

blank 


DDSNAMES 

REFRESH 

READONLY 


(ddname ^ .ddnamej [=OUt] ) 

blank 

blank 



DDSNAMES 

This op code is used to declare a data set pair as being duplicates. 
There must be one DDSNAMES card for each data set pair the user wishes 
to be treated as duplicates. The number of declarations cannot be 
changed after initialization. 

ddsname 

Is the name which must be used by all DDS macros and commands which 
refer to this DDS. The The DDSDCB must use this name in its name 
field- If this operand is omitted, the value specified as ddnamel 
will be taken as the DDSNAME. 

ddnamel 

This parameter is required and specifies the DDNAME of the primary 
data set. 

ddname2 

This parameter is required and specifies the DDNAME of the backup 
data set. 

= OUT 

Specifies that the backup should be initialized out-of -ser vice. 
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REFRESH 

This op code indicates that a DDSTATUS data set has already been 
created and that the declarations contained therein should be used 
for this run. This op code is only valid as the first card, and, if 
present, all subsequent cards will be ignored. 

READONLY 

This op code indicates that this is the backup computer and that all 
DDS outputs should be inhibited until f ailover/restart occurs. This 
op code i mplies R EF RESH , so a previously created DDSTATUS data set 
is required. This op code is only valid as the first card, and all 
subsequent cards will be ignored. 

The DDSTATUS data set will be sequential and will consist of one record 
(undefined record format) which will be the core image of the DDS 
control areas for all duplicate data sets. Thus, the needed information 
is contained for each DDS; primary DD name, backup DD name, and 
serviceability of the backup- This data set allows DDS to continue 
using the most current status for each DDS after a f ailover/restart . 

DDS lock/share logic is required since more than one task may be using 
a DDS during the same time period. Some DDS functions require that no 
other tasks be using that same function at the same time, while other 
functions can proceed in parallel with each other. Thus four logical 
states can be defined for tasks with respect to DDS: (1) locking a 
DDS, (2) waiting-to-lock a DDS, (3) sharing a DDS, and (4) 
waiting-to-share a DDS. 

The implementation of these states is accomplished by having a chain 
of DDS Lock ECBs and DDS share ECBs, both starting with the DDS control 
area for each DDS- The DDSLOCK ECB chain will consist of all tasks 
waiting-to-lock this DDS- A non-zero value in the high-order byte of 
the starting DDS lock ECB signifies that DDSLOCK is in effect for that 
task (as opposed to 'waiting-to-lock'). The DDS share ECB chain 
consists of all tasks waiting to share this DDS. The high-order byte 
of the starting DDS share ECB will contain a count of the tasks 
currently sharing this DDS. 

The locks that will be defined during initialization are DD lock/share 
ECB chains just explained. All functions which modify those chains 
(DDSLOCK, DDSUNLOCK, DDSHARE, DDSUNSHARE) must first acquire a lock on 
the DDS lock/share chain in question. 
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A sample JCL deck to run a 
program using DDS follows: 



Special Real Time Operating System test 



//SRTOS 


EXEC 


PGM=DPPINIT 




Card 


1 


//STEPLIB 


DD 


DSN=EMS370.LM7 


1, DISP=SHR 


Card 


2 


//DBINIT 


DD 


DSN=EMS370.DB1 


71 ,DISP= SHR 


Card 


3 


//DBINIT2 


DD 


DSN=EMS370,DB2 


71,DISP=SHR 


Card 


4 


//MSGDS 


DS 


DSN=EMS370 ,DBa 


71 ,DISP=SHR 


Card 


5 


//DDSTATUS 


DD 


DSN=EMS370 ,DDS 


71 ,DISP=SHR 


Card 


6 


//DDSEQ 


DD 


DSN=DDS1 ,DISP= 


SHR 


Card 


7 


//DDSEQl 


DD 


DSN=DDS2,DISP= 


SHR 


Card 


8 


//DDBPM1 


DD 


DSN=DDSBP1 ,DIS 


P=SHR 


Card 


9 


//DDBPI12 


DD 


DSN=DDSBP2 ,DIS 


P=SHR 


Card 


10 


//DDSCMPIN 


DD 


UNIT=DISK,DISP 


= (,PASS) , 










SPACE== (TRK , (1, 


1)) 


Card 


1 1 


//MSGOOT 


DD 


SYSODT=A 




Card 


12 


//SYSPRINT 


DD 


sysooT=A 




Card 


13 


//SYSUDUMP 


DD 


SYSOUT=A 




Card 


14 


//COMPRINT 


DD 


sysouT=A 




Card 


15 


//DDSCTLIN 


DD 


* 




Card 


16 




DDSNAMES 


(DDSEQ, DDSEQl 


) 


Card 


17 


DDS BP AM 


DDSNAMES 


(DDBPM1 ,DDBPM 


2=O0T) 


Card 


18 


//SYSINIT 


DD 


* 




Card 


19 




TCB 


1 




Card 


20 


TO 


PATCH 


EP=TESTPGM 1,TA 


SK=TESTPGM1 


Card 


21 




WAIT 


TO 




Card 


22 




ABEND 


1 




Card 


23 


/* 








Card 


24 



Card 1 The entry point for a Special Real Time Operating System 

execution is DPPINIT. 

Card 2 The Special Real Time Operating System load modules 

exist on this data set in executable form. 

Cards 3-4 These data sets contain the required arrays for Special 

Real Time Operating System data base. 

Card 5 This data set contains the messages previously created 

during Special Real Time Operating System SYSGEN. 

Card 6 The data set will contain a copy of the DDS control 

areas to keep a current status of all DDS declarations. 

Cards 7-10 These data sets will be the two duplicate data set pairs 

for this test run. 

Card 11 This data set is a one-track sequential data set which 

will be used by DDS if a DDS COMPARE function is 
requested. 

Card 12 This data set will receive Special Real Time Operating 

System output messages. 

Card 13 This data set will receive initialization messages 

output . 

Card 14 This data set will receive a dump if one should occur. 

Card 15 This data set will receive the output of lEBCOMPR if a 

DDS Compare Function is requested. 
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Card 16 



This data set contains the DDS input cards. 



Card 17 This card declares that DDSEQ is a duplicate data set 

name, that DDSEQ is the primary DDNAME, that DDSEQ1 is 
the backup and that the backup is in-service. 

Card 18 This card declares that DDSBPAM is a duplicate data set 

name, that DDBPM1 is the primary DDname, that DDBPM2 is 
the backup DDname, and that the backup is out-of-ser vice 

Card 19 This data set contains the Special Real Time Operating 

System initialization input cards. 

Cards 20-23 These cards control the Special Real Time Operating 
System execution. 
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OFPLIHE OTILITY PROGHIH 



I ntiodttction 

A realtiae system typically requires a detailed description of the 
environient in which it operates. This description contains inforaatioa 
of ti#o types. The first is the selection of options that are to be 
This includes both hardware and software options, which are selected 
at installation or systen generation (SYSGEN) tiae. The second type 
of environnent description encoapasses those parameters that ar® of a 
more dynamic nature. In the Special Real Tiae Operating system, these 
consist of display, data base, and message definitions. These 
definitions are initially made at Special Real Tine Operating System 
SYSGEN tiae through the use of the offline utility program DPPXUTIL. 
This same program (DPPXOTIL) is used, as the realtime system develops, 
to add new definitions or to change old ones. The offline utility 
program may be run in a partition during an online run, or on a backup 
CPO. 

The data base and message data sets are created and updated using the 
offline utility. The control cards and macro statements coded by the 
user result in the data sets being created to the user specification. 
This is shown in Figure 3-7. 



{ 



# /DPPXUCTL 
Control 
Statement 



Coded 
Source 
Macro 
Statements 



OFFLINE UTILITY 



Data Base 
Final Phase 
Processor 



Message Final 
Phase Processor 



Data Base 
Data Set(s) 



Allocated by 
DO Cards Named 
DBINIT 
DBINIT2 



Allocated by 
DP Card MSGDS 



Message 
Data Set 



Display 
Data Set(s) 



Allocated by 
DD Cards Named 
DDOUDD 
DP0UDD2 



Figure 3-7. Offline Otility Processing Overveiw 



The control statement (*/ DPPXUCTL) defines to the offline utility data 
set (s| that is to be created or modified, the locations of the source 
sacro statements to be used to create or modify the data set, and the 
function to be performed on the data set, i.e., ADD, DEL, REPL, or 
TEST. The format of the required source macro statements is different 
for each of the three typ«s of output data sets, and the description 
of these macros follows in the final phase processor descriptions. 

In addition, a facility is provided by the offline utility to allow 
the aser to isodify his source macro statement data set prior to its 
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use in generaiinq the output data set. The user requests the update 
function with a #/ DPPI'PDT control card. The offline utility prograir 
invokes the ns/VS1 update utility proaraa lEBUPDTE. Therefore, the 
user can code IPBOPDTE statements, pass them to DPPXUTIL, and have his 
source aacro data set updated in the sa ae execution as the creation of 
the output data sets. It should be noted that the offline utility 
processes in the saie sequence as the control statements it receives. 
>s a result, if the update is to take place before the online data set 
is aodified or created, the DPPXOPDT card lust precede the DPPXUCTL 
statement in the input stream. No limit is imposed by the offline 
utility on the nuaber of control statements that aay be used in one 
execution. 

Input to the offline utility must be either cards or blocked or unblocked 
card iaaqe records from a source library. The input consists of control 
statements, which define the operation to be performed by the offline 
utility and source macro statements. The macro statements may be in the 
input streaffl or in a source library. The aacro source library cannot 
contain control cards. The control statement may be in the input stream 
or Bay be a sequential data set. 

Sach control statement consists of an identifier, an operation, and 
parameters. The identifier consists of the characters #/ in columns 
1 and 2 to denote a control card. The operation must be preceded and 
followed by at least one blank. The operation describes the function 
to be performed by the offline utility. DPPXOCTI specifies that an 
online data set is to be created or modified. DPPXOPDT specifies that 
a source aacro data set is to be updated. The parameters further describe 
the operation to the utility. 

The utility program begins processing by looking in the SYSIN data set 
for a control statement. The first statement should be a control 
statement; if it is not, an error message is issued, and data in SYSIM 
will be bypassed until a control statement is found. When a control 
statement is found, it is validity checked, any errors will cause error 
messaqes to be issued and a search begins for the next control statement. 
Control statement errors do not terminate the utility program; however, 
processing foe the control statement in error will be bypassed with 
appropriate diaqnostic messages. The offline utility program terminates 
when no more control statements are to be processed. 

When a valid DPPXOCTL control statement has been processed, all the input 
source aacro statements for the control statement are read in and rewritten 
into the data set allocated to the iob by the SYSUT» DD card. This data 
set is then passed to the assembler, when a valid DPPXOPDT control 
statement is processed, the lEBOPDTS control and data statements (which 
must follow the DPPXOPDT statement in the SYSIN input stream) are read in 
and rewritten to the SYSUTU data set. This data set is then passed to 
lEBOPDTE. 



Source Dat a Set Opdate Operation 

The source macro statements used to define an online data set may be 
maintained as a sequential data set or as a member of a partitioned data 
set. These sjurce macro data sets may be created and modified by the 
offline utility. The modification of a source aacro data set is invoked 
by the #/ DPPXOPDT control statement. Figure 3-8 shows an overview of 
the update processing. 
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HI OPPXUPOT CONTROL CARD PROCESSING 



/ 

Primary 
Input 
Straam 



Input 



Write to 
SYSUT4 DD 

Input to 
lEBUPDTE 



SYSIN 
Input 



Link to 
lEBUPDTE 



Link 



Input 

Source 

Member 



Output 
Source 
Member 



Return 



Print 
Output 




Figure 3-8. Update Processing Overview 
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The format of the DPPXOPDT control statement is: 



#/ DPPXOPDT OLDSET=ddnaiae,NEWSET=ddname 
#/ Is required in columns 1 and 2. 



DPPXUPDT 

Specifies a source data set update and must be preceded and followed 
by at least one blank, 

OLDSET=ddname 

Specifies the ddname of the DD card allocating the data set to be used 
as input (SYSOTI) by lEBUPDTE. 

NEWSET=ddnanie 

Specifies the ddname of the DD card allocating the data set to be used 
as output (SYSOTZ) by lEBDPDTE. 

The lEBUPDTE control statements and input data statements must be coded 
as specified in the OS/VSl Utilities Manual , GC35-0005, and must 
immediately follow the DPPXOPDT control statement in the SYSIN input 
stream. Standard assembler language rules apply to comments and 
continuation. 



The following example shows a typical offline utility input stream for 
an update function. 



#/ 
./ 



DPPXUPDT 

ADD 

ARRAY 



ARRAY 

CHANGE 
DELETE 

REPL 
ARRAY 



OLDSET=DBASIN, NEWS ET=DBASOUT 
NAME=DBAS1 ,LIST=ALL 

NAME=ARRAY01 
ITEM NAME=ITEM101,TYPE=F 
ITEM NAME= ITEM 102, TYPE = F 

NAME=ARRAY02 
ITEM NAME=ITEM20 1, TYPE = C,LEN=1 6 

NAME=DBAS2,LI ST=ALL 

SEQ1=200,SEQ2=300 
ITEM NAME=ITEM705, TYPE=F 00000500 
NAME=DBAS3, LIST=ALL 

NAME=ARRAY05 
ITEM NAME=ITEH50 1, TYPE=A 



Source Data Set Update Control Card Example 



In this example, DD cards named DBASIN and DBASOOT may define the same 
or different data sets. A new member named DBAS1 will be created in 
,the data set defined by DD statement DBASOOT. Existing member DBAS2 
will have statement numbers 200 through 300 deleted, and statement 
number 500 will be replaced. Existing member DBAS3 will be replaced. 



Processin g an Onlin e Data Set 

The DPPXUCTL control statement requests the creation or modification 
of a data set which is normally used online. The utility program, 
after reading the source macro data set and rewriting it to the SYSUTU 
data set, links to the assembler. The link will be to the 0S/VS1 
assembler unless the user requests the use of the assembler H program 
product (5734-AS1) by coding PARM=H on the JCL EXEC card. The data in 
SYSOTU is assembled and control is returned to the offline utility. 
If the assembler return code is 8 or greater, processing for this 
control statement is aborted, and the utility attempts to read another 
control card. If the return code is less than 8, the utility loads 
the OS/VSl Loader, which loads the assembled module into virtual 
storage. Control is returned to the utility and if the return code is 
less than 8, the appropriate final phase processor is invoked by a link 
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to update the online data set. The appropriate final phase processor 
depends upon which operand was coded in the AREA= keyword of the control 
statement. Figure 3-9 shows an overview of the online data set 
processing function. 

The format of the DPPXOCTL control statement is shown below. Standard 
assembler language rules apply to comments and continuation with the 
exception that each parameter must not be split across two cards; that 
is, each parameter must be wholly contained on one card. 



#/ 



DPPXUCTL 



AREA = 



, OPTION = 



DISPDEF ) 

DBDEF 

MSGDEF 

ADD 
DEL 
REPL 
TEST 



, INPUT = I ddname 

ddname (membername) 



I , TYPE = device type ] 



#/ Must be in columns 1 and 2. 
DPPXUCTL 

Specifies an online data set is to be modified or created. This must 
be preceded and followed by at least one blank. 

AREA= 

Must be specified and must specify one of three keywords: 
DISPDEF 

Specifies that the operation be performed against the display data 
set . 

DBDEF 

Specifies that the operation be performed against the data base data 
set. 

MSGDEF 

Specifies that the operation be performed against the message data 
set. 
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Figure 3-9. Online Data Set Processing Overvieii 
I NPUT= 

Must be specified and must specify one of the follorfing: 

* 

Specifies that the input for this execution immediately follows the 
control statement in the.SYSIN input stream. 

ddname 

Specifies that the input for this execution is in the sequential data 
set allocated to the job by the named (ddname) DD statement. 

ddname (member name) 
Specifies that the input for this execution is in the "member name" 
member of the partitioned data set allocated to the job by the named 
(ddname) DD statement. The ddname and member name may consist of 
from 1 to 8 alphabetic (A-Z) or numeric (0-9) characters, the first 
of which must be alphabetic. Special characters 3, #, and $ are not 
allowed . 

OPTION= 

Must be specified; it indicates the type of operation to be performed. 
One of the following must be specified: 

ADD 

Add a new member to the online data set. 
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REPL 

Indicates to replace an existing member in the online data set and 
if the member does not exist, to add the new one. 

DEL 

Signifies to delete an existing member from the online data set. 
TEST 

Is similar to REPL; the member is assembled, listing produced and so 
forth, but the content of the online data set is not changed, 

TYPE= 

Is optional and is recognized only when AREA=DISPDEF is specified. 
If AREA=MSGDEF or DBDEF, TYPE= is ignored. When coded, it must specify 
the device type of the display hardware, i.e., 3277-1, 3277-2, 5985. 
The default, if AREA=DISPDEF and TYPE= is not coded, is 3277-2. 



The following example shows a typical input stream to the offline 
utility to process an online data set. 

#/ DPPXUCTL AREA=DBDEF,INP0T=*,0PTION=ADD 
ARRAY NAME=ARRAY09 

ITEM NAI!E=ITEI!901,TYPE=F 
ITEM NAME=ITEM902, TYPE=F 
#/ DPPXUCTL AREA=DBDEF,OPTION=REPL, * 

INP0T=DBASOUT (DBASI) 
#/ DPPXUCTL AREA=MSGDEF,OPTION=REPL * 

INPUT = MSGIN (TIMEMSG) 
#/ DPPXUCTL AREA=MSGDEF,OPTION=DEL, * 

INPUT=MSGSEQ 

Online Data Set Update Example 

In the preceding example, the following processing is being reguested. 

1. A new member (ARRAY09) is being ADDed to the online data base 
data set. The member will be created from the ARRAY and ITEM 
cards following the control statement in the input stream 
(INPUT=*) . 

2. The member named DBAS1 from the source macro input data set 
allocated by DD card DBASOUT is to be assembled. The resulting 
member (s) will REPLace corresponding members in the online data 
base data set. 

3. The member named TIMEMSG from the source macro input data set 
allocated to the job by the DD card named MSGIN is to be 
processed. The resulting member (s) will REPLace corresponding 
members in the online message data set. 

4. The seguential source macro input data set allocated to the job 
by the DD statement named MSGSEQ is to be processed- The 
resulting member names will be DELeted from the online message 
data set. 

The following example is typical of the JCL required to execute the 
offline utility program (DPPXUTIL). Following is a description of each 
of the JCL statements in the example. The 'underlined portions of the 
JCL will likely have to be changed by the user to suit the requirements 
of his operation. 
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//BUILD 


JOB 


(ACCOUNTING INFORMATION) 


//SI 


EXEC 


PG M= D P PX UT IL , P AfiM= H 


//STEPLIB 


DD 


DSN=USER .LINKLIB,DISP= SHR 


//S YSPRINT 


DD 


SYSOUT= A 


//ASMPRINT 


DD 


SY SOUT=A 


//UPD PRINT 


DD 


SYSOUT= A 


//LODPRINT 


DD 


SYSOUT=A 


//SYS LI B 


DD 


DSN=USER„M ACLI B, DISP=SHR 


// 


DD 


DSN=SYS1.M ACLIB, DISP=SHR 


//SYS OT 1 


DD 


UNIT= (SYSD A,SEP=SYSLIB) ,SPACE= (CYL, {2, 2) ) 


//SYS UT2* 


DD 


UNIT= (SYSDA,SEP=SySUT1),SPACE= (CYL, (2,2)) 


//SYSuTJ* 


DD 


UNIT=(SYSDA,SEP=SYSUT1) ,SPACE=(CYL, (2,2)) 


//SYSUT4 


DD 


UNIT= (SYSD A, SEP=SYSUT1 ) , SP ACE= (CYL , (2,2) ) 


// DCB= (RECF M= 


:FB,LRECI 


.=8 0, BLKSIZ E=3200) 


//D BIN IT 


DD 


DSN=USER-D BI , DISP=OLD 


//D BI N I T 2 


DD 


DSN=USER.D B2^ DISP= (MOD , PASS) , DCB= (DSORG=DA ) 


//MSGDS 


DD 


DSN=USER.MSG, DISP=OLD 


//DPODDD 


DD 


DSN=USER.DISP1 ,DIS P=OLD 


//DP0UDD2 


DD 


DSN=nSER.DISP2 ,DISP=OLD 


//DBASIN 


DD 


D S N= USER - S OURC E- DB. MACROS, DISP=OLD 


//DBASOUT 


DD 


DS N=USER.SOURCE. DB1 . MACROS , DISP=OLD 


//MSGIN 


DD 


DSN=USER.SOURCE.MSG.MACROSffDISP=OLD 


//MSGSEQ 


DD 


DSN=USER, SOUR CE.SEQ MSG . MACROS, DISP=OLD 


//SYS GO 


DD 


UNIT=S YSDA,SPACE= (CYL, (1,1)) , 


// DCB=(RECFM= 


= FB,LRECL 


=80, BLKSIZ E=3200) 


//S Y S I N 
/* 


DD 





(Input Control Statements) 
JCL Example 

*Not required when "PARM=H" is specified on the execute card. 
JOB 

Is a standard 0S/VS1 job card; the accounting information is dependent 
upon individual installation requirements, 

EXEC 

Is a standard 0S/VS1 EXEC card; it must specify PGM=DPPXUTIL or an 
applicable user PROC. 

PARM 

The offline utility will provide the option to print or not to print 
statements generated by the processing of a macro. This will be 
accomplished by the offline utility inserting or not inserting a PRINT 
NOGEN statement as the first statement in the Assembler SYSIN stream. 
Control will be provided through the PAEM keyword operand on the 
execute card for DPPXUTIL. This option is provided in addition to 
the option to select the 0S/VS1 assembler or the H assembler. 

The following values may be specified: 



F — Selects the 0S/VS1 Assembler. 

H — Selects the H Assembler, 

GEN — Print macro generated statements, 

NOGEN — Do not print macro generated statements. 



In all cases, the default values will be "F" and "NOGEN" 
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Valid combinations of the values are: 



r An n 




t T? 1 


D K P M 

c AK n 






IT AK n 






Jr All n 




WUv3 Jin 


P AP M 

JT ri IV Li 






FARM 




« F,NOGEN • 


PARK 




•H,GEN« 


FARM 




• H,NOGEN' 



If an invalid value is specified for the PARK operand or if the FARM 
operand is omitted, the default of P ARM=« F,NOGEN ' will be used and 
message DPPXUT25 will be printed. 

STEPLIB DD 

Defines the library containing the DPPXOTIL program and final phase 
processors and is not required if these programs reside in 
SYS1 ,LINKLIB. 

SYSPRINT DD 

Defines a data set in which printed output will be placed, or may 
specify a standard output class. 

ASMPRINT DD 

(Same as SYSPRINT) for printed output from the assembler. 

DPDPRINT DD 

(Same as SYSPRINT) for printed output from lEBOPDTE. 
LODPRINT DD 

(Same as SYSPRINT) for printed output from the loader. This may be 
a DD DOHMY to reduce printed output. 

SYSLIB DD 

Defines the data set (s) containing the macros used by the assembler. 
SYSUT1 DD 

Defines the assembler work data sets. The device classname SYSDA 
defines a direct-access device. This name (SYSDA) , if used, must have 
been generated into the 0S/VS1 system. SEP= is specified to improve 
assembler performance. 

SysUT2 DD 

(Same as SYSUT1) . Not required when "PARM=H" is specified on the 
execute card. 



SYSUT3 DD 
(Same as SYSUT2) . 

SYSUTU DD 

Defines a work data set for DPPXOTIL. The DCB parameters must specify 
RECFM=FB and a BLKSIZE that is a multiple of 80. The LRECL must be 
80. 



DBINIT DD 

Defines the data base partitioned data set that contains a member for 
every array in the data base, control information for direct access 
resident arrays and initial data for VS resident arrays. This DD card 
is required if any utility control card specifies AREA=DBDEF- 

DBINIT2 DD 

Defines the BDAM data set which contains the initial data for DA 
resident arrays. This DD card is required if any utility control 
statement specifies AREA«DBDEF. The data set described by this DD 
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card must be allocated prior to the execution of the offline utility. 
The DISP= operand on the DD card must specify (MOD, PASS) . 

MSGDS DD 

Defines the data set containing online display information. This DD 
card is required if any utility control statement specifies 
AREA=MSGDEF. 

DPOUDD DD 

Defines the data set containing online display information. This DD 
card is required if any utility control statement specifies 
AREA=DISPDEF. 

DP0UDD2 DD 

Defines the display online comment data set. This DD card is required 
if any utility control statement specifies AREA=DISPDEF and the DISPGEN 
statement specifies COMMENT=YES. 

DBASIN DD 

May have any DD NAME- In this example, the DBASIN DD name was used 
to correspond to the OLDSET= name in the source data set update control 
card example. The name chosen on the OLDSET= may be any valid DD 
name; however, it must have a corresponding DD statement. 

DBASOUT DD 
(Same as DBASIN) for NEWSET= keyword 

MSGIN DD 

(Same as DBASIN) for INPUT= in the online data set update example 
MSGSEQ DD 

(Same as DBASIN) for INPDT= in the source data set update control card 

example 

SYSGO DD 

Defines the data set to contain the object deck output from the 
assembler. This data set is used as input to the OS/VSl loader. 

SYSIN DD 

Defines the input from which DPPXUTIL gets its control statements as 
possibly some source macro statements. 



Mes sage Final Phase Processor 

The message final phase processor accepts the load modules created as 
a result of offline utility processing of DEFMSG statements and puts 
them into the online message data set- Each DEFMSG statement results 
in a member being processed in the partitioned data set allocated by 
the MSGDS DD card- 

The type of processing is determined from' the request in the control 
card, e.g., ADD, DEL, REPL, or TEST- 

The following is an example of offline utility control statements that 
would result in the invoking of the message final phase processor. 

#/ DPPXUCTL AREA=MSGDEF,INPaT=*,OPTION=ADD 

DEFMSG 7 ,ROaTE=200 ,ACT=I,TEXT= 'DUMMY MESSAGE' 

A control statement such as this would cause message number 7 to be 
added to the online message data set. The message would be a member 
with the name DPP007. 
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There are more examples and additional descriptions of the DEFMSG in 
this manual in the section describing the online message handler. 



Data Base Final Phase Processor 

The data base final phase processor receives control from the offline 
utility to process the assembled and loaded input created by the input 
cards following the AREA=DBDEF card. The function of the data base 
final phase processor is to build and modify the online data base data 
sets. 

The input is the assembled and loaded data generated from the user 
coded ARRAY, BLOCK, and ITEM macros. These macros are used offline 
only and are described in detail in the following section. 

For the purpose of the following discussion, an ARRAY is defined as an 
arrangement of data ITEMS in one or more dimensions or BLOCKS, The 
Special Real Time Operating System arrays with data items of one 
dimension only are called UNBLOCKED arrays. Arrays with two or more 
dimensions are BLOCKED arrays. 

Arrays which will reside in virtual storage during online processing 
are known as VS resident arrays. A VS resident array may be either a 
BLOCKED array or an UNBLOCKED array. An array which resides on a direct 
access device during online execution is known as a DA resident array. 
A DA resident array must be a BLOCKED array. 

A 'LOGGABLE' array is a VS array for which logging has been requested. 
A 'LOGGING' array is a DA resident array into which a VS resident 
logable array is being logged. For a more detailed description of data 
base logging refer to the section in Chapter 2 entitled, "Data Base 
Logging- " 

The Special Real Time Operating System data base consists of VS resident 
arrays and DA resident arrays. Data base logging will be performed on 
a demand basis or on a cyclic basis if cyclic logging is SYSGENed. 

The offline utility program and the data base final phase processor 
create and update the data base. The type of array and the operation 
to be performed are defined through the utility control statements and 
the offline macros ARRAY, ITEM, and BLOCK. 

The ARRAY macro is used to define the array, its characteristics, and 
its dimensions. The BLOCK macros define the boundaries within the 
dimensions of the array. The ITEM macro defines each item or element 
of the array and its initial values. An item control block is created 
to define each ITEM defined. The item control block contains the item 
name, the type of data, the length of data, the repetition factor of 
the item, and the displacement into the array of the start of the data 
item- 

The operation to be performed on the data base is defined to the offline 
utility by the OPTION= parameter on the #/ DPPXUCTL input control 
statement. The operation types and meanings are shown as follows: 

ADD 

Indicates a new array is to be added to the data base. If the data 

base already contains an array with the same name, the new array will 

not be added, and an error message will be issued. 

REPL 

Indicates that a new array is to be added to the data base. If the 
data base does not contain an array with the same name, the array will 
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be added. If the data base does contain the named array, it will be 
replaced in the data base. 

DEL 

Indicates that an existing array is to be deleted from the data base. 
If the array does not exist, an error message is i#ritten. 

TEST 

Is similar to REPL except the data base is not modified. 



2§ta Base Data Sets 

The. Special Real Time Operating System data base consists of one 
partitioned data set (DSORG=PO) and one or more direct data sets 
(DSORG=DA) , The partitioned data set (PDS) is allocated at the Special 
Real Time Operating System SYSGEN time and is referenced in realtime 
by the DD card named DBINIT. The direct data set is also allocated at 
the Special Real Time Operating System SYSGEN time and is referenced 
by the //DBINIT2 DD card. 

The PDS contains a directory entry for every array in the data base. 
Information in the directory entry is used for data base initialization. 
The members of the PDS contain the Item Control Blocks for each arra'y 
in the data base. For VS resident arrays the member containing the 
Item Control Block also contains the VS resident array and its initial 
data. For DA resident arrays the PDS member containing the Item Control 
Block also contains control information used to locate the corresponding 
DA array in the direct data set. 

There can be only one PDS in the data base. However, additional direct 
data sets can be allocated and become part of the data base. Once an 
additional direct data set has been referenced during execution of the 
offline utility, any further reference to this data set as part of the 
data base must be made through a DD card with the DD name the same as 
the DD name used on the DADD or the LOGDD keyword on the ARRAY macro 
used to create the array. This is because the DD name becomes part of 
the control information written into the PDS member for the array. 

Secondary data bases may be created by the user. To do this, he would 
create a PDS and one or more direct data sets and reference them through 
the DBINIT and DBINIT2 DD cards. 

Warning : The data base data sets contain records with references to 
and dependencies on other records and members. These 
references and dependencies are constructed by the offline 
utility program DPPXUTIL, and the data sets must not be 
modified except by DPPXUTIL. This precludes moving or 
copying an entire data base data set, and also prohibits 
modifying their content by adding or deleting records or 
members, or by changing block sizes. Concatenation of data 
base data set groups for realtime execution is not allowed. 
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OFFLINE MACROS 



The following pages describe the operands and functions of the offline 
macros. For convenience they are listed in alphabetical order. 

Some of the operands on the data base offline macros have been designed 
to accept self-defining terms or absolute expressions in place of an 
actual value. This will provide greater flexibility in design and 
maintenance of data base arrays. The macros and operands which provide 
this capability are shown below. 



MACROS 



OPERANDS 



ARRAY 



BLKCT= 
BLKSIZE= 



BLOCK 



Start number 

,stop number 



ITEM 



LEN= 
RPT= 
DISP = 



EXAMPLE: 

The following will illustrate some self-defining terms and absolute 
expressions, the format of that can be used in the ARRAY, BLOCK, and 
ITEM macros. 



DATA 


DSECT 






COUNT 


EQU 


10 




START 


DS 


OD 




A 


DS 


F 




B 


DS 


D 




C 


DS 


F 




STOP 


DS 


OD 




SIZE 


EQU 


STOP - START 






ARRAY 


NAME=ARAY, BLKCT= (COUNT 


) ,BLKSIZE= 




BLOCK 


(L« A) , (C-B) 






ITEM 


TYPE=C,LEN= (L 'A) ,DISP={A- 


START) 




ITEM 


TYPE=C,LEN= (COUNT) ,DISP=tt 


,RPT= (L* B) 



Note: 



• Self- defining terms and absolute expressions must be enclosed in 
parenthesis. 

• Care must be taken not to become "H" assembler dependent. 

« No validity checking of block numbers will be done in the BLOCK 
macro if a se If -defining term or absolute expression is used on a 
block macro. 



No validity checking will be done to prevent items from overlapping 
when the "DISP=" operand is used. 
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ARRAY 

The ARRAY macro is used to define a data base array to the database 
offline utility. 



[symbol] 



ARRAY 



( NAME=name 1 
(NUMBER=number) 

[.™"- Ills)] 



REIN1T= 



LOCATE= 



,BLKCT= 



,BLKSIZE= 



— n 

YESJ J 

m 

' BLOCK ] 
I number I 
I (self -defining term) j 
^ (absolute expression)) 



number 
(self -def i 
(absolute 



ning term) | j 
expression)) J 



|^,DADD= ddname j 



,BNDRY= 



DBLWD 

PAGE 

MIN 



|l0GNAME= namej 
|^LOGDD= ddnamej 

] 



|LOGWRAP=name 
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NAHE= 

Is a 1 to 8 byte alphameric name that conforms to standard OS naming 
conventions for members of a partitioned data set. The array name 
for each array must be unique for all arrays in the data base. The 
NAME and NUMBER parameters are mutually exclusive. 

NOMBER= 

Is a decimal number from 1 through 255 by which the array may be 
referenced during online data base processing- The total number of 
arrays in the data base is not limited to 255^ however, the maximum 
number of NUMBERed arrays is 255- An entry will be allocated in the 
online tables for each number from one to the highest assigned array 
number even though all numbers do not have an array built for them 
(i.e., two arrays are created - NUMBER=2 and NUMBER=10 - this will 
create only two arrays in the data base but will create 10 entries in 
the online tables.) For this reason, numbers should be assigned in 
ascending sequence starting with one. Skipped numbers are valid, but 
will result in wasted virtual storage and extra processing time for 
online data base processing. The NAME and NUMBER parameters are 
mutually exclusive, 

INIT= 

Is used to determine whether a VS resident array is to be initialized 
at data base initialization time- If YES is specified, space will be 
allocated in VS, and the data specified in the ITEM cards for this 
array will be moved from a direct access device into the allocated 
space in VS. If NO is specified, space will be allocated in VS, and 
no data will be moved into the allocated space. (The space may contain 
residue data from previous programs.) The The default value for this 
parameter is NO. This parameter is ignored if DA is specified on the 
LOCATE parameter- 

REINIT= 

Defines reinitialization action to be taken after a Special Real Time 
Operating System restart. The parameter is valid only if LOCATE=VS 
is specified and if logging is specified for the array. If REINIT=YES 
is specified, the data from the most recently logged copy of the array 
will be read into the space allocated to the array after the restart 
occurs. Reinitialization will be bypassed by the data base online 
initialization routines if the logged copy is not at the same update 
level as the array which was loaded at the Special Real Time Operating 
System initialization. This would occur if the array had been 
redefined through the offline utility programs. 

If REINIT=NO is specified or the parameter is omitted, the content of 
the array will not be modified after a restart occurs. 

LOCATE= 

Is used to determine whether the array is to reside on a direct access 
device or in virtual storage during online data base processing. If 
VS is specified, the array will be initialized in virtual storage in 
accordance with specifications of the INIT parameter. If DA is 
specified, no initialization will take place at data base 
initialization time. The default value for the LOCATE parameter is 
VS. 

BLKCT= 

Determines whether the array is blocked or unblocked. If this 
parameter is omitted, the array is assumed to be unblocked and, 
therefore, must reside in virtual storage. A number from 1 through 
32767 will specify the exact number of data blocks that will be created 
for this array. The number of data blocks can be implied by specifying 
BLOCK on the BLKCT This indicates that the highest block number 
specified on a BLOCK macro for this array will determine the number 
of data blocks for this array- BLKCT is required if DA is specified 
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on the LOCATE parameter. When BLKCT=n is specified, there cannot be 
either more BLOCK macros than n or a BLOCK macro cannot specify a 
number greater than n. 

Examples : 

ARRAY NAME=EXAMP 1, BLKCT=2 

BLOCK 

ITEM 



BLOCK 
BLOCK 



ITEM 
ITEM 



This is invalid because BLKCT=2 is specified but the array has 3 BLOCK 
macros. 

ARRAY NAME=EXAMP2,BLKCT=a 
BLOCK 1,5 
ITEM 

This is invalid because BLKCT=4 was specified and the BLOCK macro has 
a request for 5 blocks. 

ARRAY NAME=EXAMP 3,BLKCT=10 

BLOCK 2,5 
ITEM 

This example is valid and will build an array with 10 blocks in which 
blocks 2 through 5 will be created with the initial data as requested 
in ITEM cards and blocks 1 and 6 through 10 will also be created but 
will have initial data of binary zeros. 

If BLKCT=BLOCK were specified, the. number of blocks created would be 
the same as the highest block number generated by a BLOCK macro. 

ARRAY NAME=EXAMPa, BLKCT=BLOCK 

BLOCK 1,5 
ITEM 



BLOCK 
BLOCK 



ITEM 
ITEM 



The above example would result in a block count of 7 as block numbers 
are assigned sequentially when no operands are specified. 

BLKSIZE= 

Specifies the number of bytes to be allocated to each block of data 
in this array. This parameter is ignored if the BLKCT parameter is 
omitted. If the BLKSIZE parameter is omitted and the BLKCT parameter 
is specified, the size of the first data block described by ITEM macros 
for this array will determine the block size for all blocks in this 
array. The maximum block size is limited to the track capacity of 
the device to which the array will be- allocated. If the amount of 
data specified in the ITEM cards for the first BLOCK is greater than 
the data set block size, the data block will be truncated to data set 
block size and this will be the size for all subsequent blocks. If 
subsequent blocks generate less data than the first BLOCK, they will 
be padded with binary zeros to the same size as the first block. If 
subsequent blocks exceed the size of the first block, they will be 
truncated. When BLKSIZE=n is specified, each BLOCK will be created 
n bytes long . 
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DADD= 

Specifies the name of a data definition (DD) statement which describes 
a BDAM data set where space for this direct access resident array will 
be allocated. This parameter is required if DA is specified on the 
LOCATE parameter; however, if VS is specified on the LOCATE parameter, 
the DADD parameter is ignored, 

USE = 

Is a code from 1 to 7 which indicates the expected frequency of 
reference to items in the array. The arrays are loaded into virtual 
memory based upon this code. Code 1 indicates the highest usage, and 
code 7 has the lowest usage. If the USE parameter is omitted or if 
an invalid value is specified, a value of 7 will be assumed as the 
default use code. This parameter is ignored if DA is specified on 
the LOCATE parameter. 

BNDEY= 

Is used to determine the boundary alignment for a virtual storage 
resident array at data base initialization time. If the parameter is 
omitted or if DBLHORD is specified, the array may be initialized 
starting on any doubleword boundary. If PAGE is specified, the array 
will be initialized to start on a virtual storage page boundary. 
Specification of MIN will cause Data Base Initialization to do 
calculations based on the array length and position the start of the 
array so that it will be contained in the smallest possible number of 
virtual storage pages. 

Those arrays for which logging is specified will have a 2U-byte logging 
header appended to the front of the space allocated in VS. For 
boundary alignment purposes, the first byte of the logging header will 
be considered the start of the array. 

The following operands describe the logging array associated with a VS 
array and the logging characteristics of the array being defined. 
Logging of the array will not be allowed if they are not specified. 
Since a DA resident array is allocated in response to these operands, 
they should not be specified if logging is not required. 

L0GNAf1E = 

Specifies a 1 to 8 character name to be used as the array name of a 
direct access resident array where the virtual storage resident array 
is to be logged. The log array name must conform to the same standards 
and conventions as set forth under the NAME parameter. This parameter 
is ignored if DA is specified on the LOCATE parameter. If this 
parameter is omitted and VS is specified* on the LOCATE parameter, no 
logging will be performed. 

LOGDD= 

Specifies the name of a data definition statement which describes a 
BDAM data set where space can be allocated for the logging array where 
this array is to be logged. This parameter is required if VS is 
specified on the LOCATE parameter and if a name was specified on the 
LOGNAME parameter. This parameter is ignored if DA is specified on 
the LOCATE parameter, 

LOGFREQ= 

Indicates by a code of 0 to 3 the frequency at which this array is to 
be logged. A code of 0 indicates that it is to be logged only on 
demand. Codes 1 to 3 are used in conjuntion with system generation 
parameters to specify the log frequency. A code of 1 is the highest 
frequency, and 3 is the lowest frequency. If the LOGFREQ parameter 
is omitted, or if an invalid value is specified, a value of 0 will be 
assumed. This parameter is ignored if DA is specified on the LOCATE 
parameter. 
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LOGCOPY= 

Specifies the number of history copies of this array for which space 
is to be allocated in the logging array. If the LOGCOPY parameter is 
omitted or if 0 is specified, a value of 1 will be assumed as the 
default value. This parameter is ignored if DA is specified on the 
LOCATE parameter. 

LOGWRAP= 

Specifies the name of a user-written load module to be given control 
when the last block of the logging array has been filled and wrap 
around will occur on the next request to log this array. This 
parameter is ignored if DA is specified on the LOCATE parameter. 

The load module will be entered via a PATCH to the load module as a 
dependent task. The parameter field will be eight bytes and contains 
the name of the array for which the logging array wrapped around. 

The following chart shows the ARRAY macro operands, which are required 
and which are optional for the creation of any type array. 



Operands 


VS Array 
Unblocked 


VS Array 
Blocked 


DA Array 
Blocked 


VS Array 
with Logging 
Unblocked 


VS Array 
with Logging 
Blocked 


NAME 


R 


R 


R 


R 


R 


NUMBER 












INIT 


O 


0 


I 


0 


0 


REINIT 


O 


0 


I 


O 


0 


LOCATE 


O 


0 


R 


o 


0 


BLKCT 


* 


R 


R 


* 


R 


BLKSIZE 


I 


0 


0 


I 


0 


DADD 


I 


I 


R 


I 


I 


USE 


o 


0 




o 


0 


BNDRY 


o 


0 




0 


0 


LOGNAME 


** 


** 




R 


R 


LOGDD 


I 


I 




R 


R 


LOGFREQ 


I 


I 




0 


0 


LOGCOPY 


I 


I 




O 


0 


LOGWRAP 


I 


I 




0 


0 



R - REQUIRED OPERAND 
O - OPTIONAL OPERAND 
I - IGNORED OPERAND 

* - THE PRESENCE OF THIS OPERAND WOULD CHANGE THE ARRAY FROM 
UNBLOCKED TO BLOCKED 
** - THE PRESENCE OF THIS OPERAND WOULD CHANGE THE ARRAY INTO 
A LOGABLE ARRAY. 
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BLOCK 



The BLOCK macro is used to define data blocks to the Data Base Final 

Phase Processor. Each block in an array will have identical dimensions. 
Two consecutive BLOCK macros are not allowed. The BLOCK macro must be 
followed by an ITEM macro. 



















start number | 




symbol 


BLOCK 




(self -defining term) > 










(absolute expression) ) 










end number | 










(self-defining term) | 










(absolute expression) 1 















start number 

Is the number to be assigned to the data block described by the ITEM 
macro statements following this macro statement. If this parameter 
is omitted, the next sequential block number will be assumed. The 
lowest valid block number is 1. 

end number 

Is the number to be assigned to the last data block described by the 
ITEM macro statements following this macro statement. This parameter 
is not required when only one data block is described by the BLOCK 
macro. This parameter causes the data block described to be duplicated 
and assigned a block number for each consecutive number from the start 
number through the end number. The value of the end number must be 
greater than the value of the start number. 

Block numbers should be assigned in consecutive, ascending sequence 
starting with the number 1. Missing block numbers between 1 and the 
highest block number specified will cause the generation of a block 
of binary zeros to be generated for each of the missing numbers. 

If the BLKCT parameter was not specified on the ARRAY macro, the BLOCK 
macro will be ignored. The BLOCK macro must not specify a block number 
greater than the value specified in the BLKCT parameter on the ARRAY 
macro. 

EXAMPLES : 

ARRAY NAME=BLKEX AM,BLKCT=BLOCK 

BLOCK 

ITEM TYPE=H,INIT=21 
BLOCK 10 

ITEM TYPE=N 

This example will create an array of 10 blocks with each block two 
bytes long- Block 1 will be initialized to 2 1 , while 2 through 10 will 
be binary zeros. 

ARRAY NAME=XMP,BLKCT=1 0 

BLOCK 3,5 

ITEM TYPE= F, INIT=-1 

This example will create an array with ten 4-byte blocks. Blocks 1 
and 2 will be initialized to binary zeros, blocks 3, 4, and 5 to binary 
ones, and blocks 6 through 10 to binary zeros. 
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ARRAY 



NAME=BLKEX ,BLKCT=BLOCK 

a 

ITEM TYPE=C,INIT = » A« ,LEN=1 0 

6 

ITEM TyPE=C^INIT = » B» ,LEN=6 
7 

ITEM TYPE=F 
10,15 

ITEM TYPE=F, INIT=-1 



BLOCK 



BLOCK 



BLOCK 



BLOCK 



BLOCK 



ITEM TYPE=C,LEN=5 



The above example will create an array with 16 blocks, each having 10 
bytes- Blocks 1, 2, and 3 will each have 10 bytes of binary zeros. 
Block a will be the character 'A* -(HEX 'CI') followed by 9 bytes of 
blanks (HEX •aO»). Block 5 will be 10 bytes of binary zeros. Block 
6 will be the character "B* -(HEX »C2'), 5 bytes of blanks (HEX •40»)/ 
followed by U padding bytes of binary zeros. Block 7 will be fullword 
aligned and will have 4 bytes of zeros (F) followed by 6 bytes of 
padding, also binary zeros. Blocks 8 and 9 will each have 10 bytes of 
binary zeros. Blocks 10 through 15 will also be fullword aligned, each 
containing 4 bytes of binary ones (INIT=-1) followed by 6 bytes of 
padding (binary zeros). Block 16 will be 1 0 bytes long with the first 
5 bytes being blanks (HEX •40«) and 5 bytes of binary zeros. 
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ITEM 



The ITEM macro is used to define, to the data base offline utility, a 
data item to be contained in a data base array. 



symbol 



ITEM 



TYPE == type 



[ ,NAME= symbol] 

[ ,INIT= value J 

(number \ ' 

,LEN=| (self-defining term) I 
((absolute expression)). 



RPT= 



vame j j 

(self-defining term) I | 
(absolute expression) J j 



'number 
DISP=| (self-defining term) 
l_ ((absolute expression) 



NAME= 

Is a 1 to 8 byte alphanumeric name. The ITEM name for each ITEM must 
be unique for all items in the entire data base. 

ITEM names may be assigned to ITEMs in the first block of a blocked 
array and will be applied to all blocks of that array. Names may be 
coded for ITEMs in succeeding blocks, but the names Mill be ignored; 
that is, they will not appear in any Special Real Time Operating System 
ITEM name lists and will not be checked for duplication. 

TYPE= 

Is required and must be one of the following: 



TYPt 


DEFAULT 
LENGTH 


DEFAULT 
ALIGNMENT 


DATA 
TYPE 


MaXSMUM 
LFN = 


A 




' ■ 

Fullivord 


Addrebs Constaiil 


1 1 

4 


F 


4 


Fullword 


Fixed Point 


4 


H 


2 


Hiiifword 


Fixed Poifi! 




D 


H 


Doublcword 


Floalmg Point 


K 


t 


4 


Fuiiword 


Floaling Pi)inl 




P 


1 


Bylr 


Packed Dcciniai 


I. 


B 


1 


Bylc 


Binary 




C 


1 


Bylc 


Chaf acler 




X 


I 


Bylc 


Hexadecimal 




N 


0 


None 


None 


2Sh 



Note: The "A" type must be specified in no n- relocatable terms or 
expressions since it will not relocate addresses. 

The "N" type allows the user to give an additional name or 'alias 
name' to the ITEM which immediately follows the null item, or 
it allows the user to generate a name which will define one or 
more of the following items which have no name assigned. The 
INIT and RPT parameters are ignored. 
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The following examples shows the use of the TYPE=N operand: 



ARRAY NAME=NULLEX 

ITEM NAME=NULLO 1A,TYPE=N 

ITEM NAME=NULLO 1B,TYPE=N 

ITEM NAME=NULLO 1^TYPE=F,INIT=27 



In this example the null items named N0LL01A and NULL01B will have 

the same displacement into array NULLEX as item N0LL01. A GETITEM 

TYPE=ADDR during online processing for item name NULL01B would return 
the same address as for name NULLOI- 

LEN= 

May be any integer value from 1 through 256, inclusive. When 
coded, boundary alignment is negated. LEN= coded on a TYPE=N 
will determine the length of data to be returned by a GETITEM 
null or alias name. This is shown in the following example: 



ARRAY NAME=NULLEX1 

ITEM NAME=NULLALL,LEN=16,TYPE=N 

ITEM NAME=N0LL1 A, TYPE=A 

ITEM NAME=NULL1 B,TYPE=D 

ITEM NAME=NULL1C,TYPE=F 

ITEM NArTE=NULLPART, LEN=2,TYPE=N 

ITEM NAME=NULL2C, TYPE=F 



In this example, an online GETITEM TYPE=DATA for item name NULLALL 
would get all the data for items NULL1A, NULL1B, and N0LL1C. A GETITEM 
TYPE=DATA for name NULLPART, however, would get only the first two 
bytes of data from item NULL2C. 

The LEN parameter is required for types B and P if initial data is 
specified on the INIT parameter. 

The LEN parameter can be used with type N to determine the total length 
of subsequent unnamed items. 

The LEN parameter for types A, E, and F may be specified as a value 
from 1 through If the parameter is omitted. or an invalid value 

is specified, the default length of 4 will be assumed. 

The LEN parameter for type H may be specified as a value of 1 or 2. 
If the parameter is omitted or an invalid value is specified, the 
default length of 2 will be assumed. 

The LEN parameter for type D may be specified as a value from 1 through 
8. If the parameter is omitted or an invalid value is specified, the 
default length of 8 will be assumed. 

The LEN parameter may be specified for type C- However, if it is 
omitted, the number of characters, not including the enclosing 
apostrophes, specified on the INIT parameter will be used as the 
length- 

The LEN parameter may be specified for type X- However, if it is 
omitted, the number of characters specified on the INIT parameter will 
be used to determine the length. If the number of characters in the 
INIT parameter is odd, 1 will be added to the number, and the sum is 
divided by 2 . If the number of characters in the INIT parameter is 
even, the number will be divided by 2- The result of the division 
will be used as the length. 

INIT= 

Specifies the initial data to be placed on the data base for this 
item. If the INIT parameter is omitted and the TYPE is C, the initial 



LEN= is 
it em 
on a 
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data Mill default to blanks. If the INIT parameter is specified and 
the TYPE is C, the initial data must be enclosed in single apostrophes 
and must conform to assembler language specifications for a 
character-type constant. The default data for all other types will 
be zeroes- 

RPT= 

Is a repetition factor to determine the number of times the initial 
data for this item will appear on the data base as part of this item. 
If the RPT parameter is omitted or specified as 0, the default value 
of 1 will be assumed. The value specified for this parameter includes 
the original copy of the item data. For example, "HPT=1" gives only 
the original item data; "RPT=2" gives the original item data plus one 
copy of the item data. 

DISP= 

Provides the capability to specify the displacement into an unblocked 
array or the displacement into a block of a blocked array where the 
initial data on the ITEM macro will start. 
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DEFMSG 

The DEFMSG macro is used to define messages to be used Joy the message 
writer function. The maximum length of a message including variates. 
However, when defining a message, the length should conform to the 
length restrictions of the device (s) to which it will be routed- 













,TEXT=*data' 


[ symbol ] 


DEFMSG 


number, ROUTE=code [^,ACT= 


III! 


[..DATE^jllgj 













number 

Is a three digit (00 1-999) unique message number with the first digit 
indicating the subsystem- (The numbers from 001-099 and 800-899 are 
reserved for use by the Special Real Time Operating System.) 



ROUTE= 

Defines routing code (0-255). Codes are assigned Codes are assigned 
(during SYSGEN) indicating the types of output devices. Examples 
would be a display unit or display group, a printer or printer group. 
By convention the codes 1-9 are reserved for use by the Special Real 
Time Operating System, 



ACT = 

Defines action code. Codes are assigned to indicate the type of action 
required in connection with a message. 

I — Information (default if operand omitted) . 
A — Action required. 

D — Operator/user decision required. 

DATE= 

Indicates whether the date will be affixed to the message during online 
operations. 



YES — Affix date. 

NO — Do not affix date. 



TEXT= 

Defines the text of the message and the variables to be supplied by 
the user when the message is requested during online execution. The 
text is a character string, enclosed in apos trophies , with the 
variables positioned in the string at the position they should appear 
in the output message- Variables are specified by coding information 
in the following format: 



#cf s# 



Where 



# is a delimiter character and must appear before and after the 
other specifications. No blanks are allowed between them. 

c defines the number of characters to be occupied by this variable 
in the output message. 

f defines the type of data conversion to be performed on the data 
being output. 

s specifies the position of this variable in the variable list 
that is passed by the calling program when the message is 
selected for output- 
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The maximum number of variables allowed is 10, The maximum message 
length, including variables, is 255 characters. The message will be 
truncated by the message writer if necessary to conform to the line 
length restrictions of the device to which the message is routed. 

The variable data is converted to alphanumeric characters as defined 
by the variable specification. The valid character specifications 
and associated conversion actions are as follows: 

F The four bytes at the address specified will be converted to 
decimal and inserted into the message, 

H The two bytes at the address specified will be converted to 
decimal and inserted into the message. 

C Data beginning at the address specified, for the length specified 
in the format specification (c above) will be moved into the 
message. It is assumed that the data consists of 'printable' 
characters . 

X The data beginning at the address specified is converted to 

hexadecimal characters and moved into the message. If the number 
of characters allocated in the message is even, data is converted 
beginning with the first 4 bits at the address specified, and 
each 4 bits following are converted to a character until the 
message field is filled. If the number of characters allocated 
in the message is odd, the first 4 bits of the byte at the 
address specified are skipped, and conversion proceeds as above. 

B The data beginning with the byte specified by the address is 
converted, each bit being converted to a character (1 or 0). 
If the number of characters allocated in the message (c) is an 
even multiple of 8, data conversion begins with the first bit 
of the first byte at the address. 

If c is not a multiple of 8, c is divided by 8 , and the value 
1 is added to the quotient (the remainder is dropped) . This 
determines the number of bytes (n) from which data will be 
converted. The right most c bits of the n byte field will be 
converted to characters and moved to the message. 

The following figure shows how the data would appear in the message if 
converted according to various variable specifications. In all cases, 
assume that the user has passed the address of a 4-byte area which 
contains x'D3042F00'. 
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Variable Output Position of Bit 

S pecification Characters Selected f or Conversio n 

#1Xn# 3 LOH~order of 4 bits 

of first byte 

#2Xn# D3 Entire first byte 

#3Xn# 304 Low-order H bits of first byte 

and entire second byte 

#6Xn# D3042F Entire first 3 bytes 

#8Bn# 11010011 Entire first byte 

#5Bn# 10011 Low-order 5 bits of first byte 

#3Bn# Oil Low-order 3 bits of first byte 

#16Bn# 1101001100000100 Entire first two bytes 

#13Bn# 1001100000100 Low-order 5 bits of first byte 

and second byte 

Figure 3-10- Hexadecimal and Binary Variable Descriptions 
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DATA BASE BDAM DATA SET COMPRESS 



The data base BDAM data set compress program DPPXDBCP provides the 
capability to recover lost space on data base BDAM data sets. 

A single execution of the compress program can be used to compress all 
BDAM data sets in a single data base. However, a single execution of 
the compress program cannot be used to compress BDAM data sets from 
more than one data base. 

JCL reguirements are: 

// EXEC PGM=DPPXDBCP Defines program name to be executed. 

//STEPLIB DD Defines the data set which contains the 

compress program. 

//SYSPRINT DD SYSO0T=A Output message data set. 

//SYSUT1 DD Defines a BDAM data set to be used by 

the compress program. 

The space allocated to this data set and the data set block size must 
be at least as large as the largest used by a BDAM data set to be 
compressed. 

//DBINIT DD Defines a data base partitioned data 

se t. 



//ANYDADD DD Defines a data base BDAM data set which 

is part of the same data base as the 
PDS defined by the DBINIT DD card. The 
DD name used here must be the same as 
the DD name used during execution of 
the offline utility. 



There may be a DD statement for every 
BDAM data set associated with the PDC 
defined by the DBINIT DD statement. 



Example 1 is a sample set of JCL to create a data base PDS and three 
associated BDAM data sets. Example 2 shows a sample of how the data 
base data sets are referenced during execution of the offline utility 
program. 

Example 3 is a sample of the JCL required to collapse the BDAM data 
sets described in Examples 1 and 2. Notice that the DD names used to 
describe the data base data sets in Example 3 are identical to those 
DD names used in Example 2. 

The SYSUT1 DD statement in Example 3 allocates two cylinders of space. 
This corresponds to the DBINIT2 DD statement in Example 1 which is the 
largest BDAM data set in this data base. The SYSUT1 DD statement in 
Example 3 specifies a data set BLKSIZE of 13030. This corresponds to 
the USERDADD DD statement in Example 1 which has the largest data set 
BLKSIZE in this data base. 
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The SYS0T1 DD statement in Example 3 may be given a disposition of NEW 
or OLD, but must never be given a disposition of MOD. 



/ / TTl V TP 

// JtXEC 


PbH— lEroR 1 «♦ 






T\n r\CM— r*A*PRni2ici hmtt— evens 






uxor — 1 #uAl i«V3 1 » VUJj— oiK— fr itU U 1 # 




// 


SPACE- (CYL, (2, , 10) 1 




// 


nr* n— /d wr* i?m— n m ifCT "71? — i '3n'3n\ 

L/C tJ— (K £iUf H — U^DliRjX ^Jli— _l jU -3U ) 






nn n Q M— n H Ti R n c o ftmt t— c vcn * nx cd- 
U U UJB— yfllADAjZ rUHX 1— oIjUAy UXoF' 


— \ £, L. A 1 iftj j f 


/ / 






// 


DCB= (RECFM=ar BLKSIZE=20ii8, DSORG=DA) 




//USE RD Add 


DD DSN=USERDADD,ONIT=SYSDA,DISP 


= (£.C AILG) , 


// 


VOL=SER=PPL00I,SPACE=iTRKti5l.) , 




// 


DCB= (RECFM=U,BLKSIZE=I3030,DSORG=DA) 




//anydadd 


DD DSN=ANIPApD,ONIT=SYSDA,DISP= 


(*.CATLG) , 


// 


VOL=SER=PPL00nSPACE=lTRK^ (5}.) , 




// 


DCB= (RECFM=U,BLKSIZE=20a8r DSORG=DA) 





EXAMPLE Ij: Creating Data Base Data Sets 



Note: The underlined portions of the JCL in Examples 1, 2, and 3 are 
the only portions which may be changed from the way they appea 



// EXEC PGM=DPPXUTIL 



//DBINIT DD DSN=DATABAS1 ,DISP=OLD 

//DBINIT2 DD DS N= DATAB AS2 ,D ISP= (MOD , P AS S) , DCB=DSORG=D A 

//USERDADD DD DSN=USERDADD,DISP= (MOD, PASS) ,DCB=DSORG=DA 

//ANYDADD DD DS N= ANID ADD, DI SP= ( MOD, PASS ) , DC B= DS ORG= D A 



//SYSIN 



DD * 



EXAMPLE 2: Offline Utility use of Data Sets 



// EXEC 
//STEPLIB DD 
//SYSPRINT DD 
//SYSUT1 
// 

//DBINIT 
//DBINIT2 
//ANYDADD 
//USERDADD DD 



PG M=DPPXCBCP 

DSN=VAN370.LMLIB.DISP=SHR 
SYSOUT=A 

DD DSN=&&SYSUT1,UNIT=SYSDA,SPACE= (CYL, (2).) , 
DC B= (RECFH=0,FLKSIZE=13030 ,DSORG=DA) 
DD PS N= DATA BAS1,DISP= OLD 
DD DSN= DATA BAS2,DISP= OLD, DCB=DSORG=DA 
DD DSN= ANIDADD,DISP=OLD,DCB=DSORG=DA 



DSN= USERDADD, DISP= OLD, DCB=DSORG=DA 
EXAMPLE 3: Compress Program JCL 
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CHA£TER_fii QPEMTOR^S RIZIMNCE 



INTRODOCTION 

This section of the manual is intended to be used at the CPU main 
console as an operator's manual. Certain information that is normally 
found in this section of a Description and Operations Manual is 
doc?umented in the previous chapter in the section entitled, "Pre-SYSGEN 
Initialization" and will not be duplicated. 



The Operator's Reference contains the Special Real Time Operating System 
operation information. It is to be used as part of the operator's 
library. This section is intended for the system operator, but some 
sections are also of interest to operators at secondary consoles or 
terminals- 



The user of this section should have a thorough knowledge of 0S/VS1 
operation. This section is not intended to replace 0S/VS1 operator 
reference material. 



The JCL required for realtime execution will vary greatly for each 
account and will most likely be provided to the operator by the system 
programmer. Therefore, the JCL requirements are documented in the 
section entitled, "System Initialization". 



The information in this section is intended to assist the operator 
running the Special Real Time Operating System and in diagnosing the 
Special Real Time Operating System control statement errors. It is 
organized as follows: 



• Normal Operating Procedures 

• Control Card Information 



• Two-Partition Operation 



• Failover/Restart 



• Normal Termination Procedures 



• Abend Codes 



• The Special Real Time Operating System Messages 



NORMAL OPERATING PROCEDURES 

The Special Real Time Operating System executes as an 0S/VS1 job which 
does not terminate normally. It is entered into the system through 
JCL just as any 0S/VS1 job. The Special Real Time Operating System 
has its own messages with operator action for some, these are described 
in this section under messages. 
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After the Special Real Time Operating System job has been started and 
the OS job started, message appears, the Special Real Time Operating 
System issues a WTOR 'SRTOS INPUT MESSAGE PROCESSING AWAITING REPLY', 
and leaves the reply outstanding. This allovs the operator to 
communicate ifith the Special Real Time Operating System. The commands 
which are defined as part of the Special Real Time Operating System 
are : 



CANCEL , ope rands 
RE PORT, operands 
DREC, ope rands 
DDSC NT RL, operands 
DLMP, ope rands 
MSGRC, operands 
QS , ope rands 
ST AE, operands 
STOP 



Each of these commands requests a specific service. Other commands 

may be defined by other PRPQs or program products or by the user through 

the IMP macro of SYSGEN. 

The operator may enter a command by replying to the MTOR in the 
following format: 

, SLAVE [ ,P!,P2, . . . ,Pn]|~l , 
[,P1,P2 . . .Pn] jj 

R XX is the format required by 0S/VS1, and xx is the message number 
to which the reply responds. The content of the reply will be in a 
standard format. The command verb is the first element of the entry. 
It may be selected from any valid IMP command defined at SYSGEN. 

If two- partition operation is SYSGENed and active, the keyword SLAVE 
may be included as the second element. If included, the command will 
be processed in the SLAVE partition. If SLAVE is omitted or two 
partition operation is not SYSGENed, the command will be processed in 
the master partition. 



r XX, 'command 



Parameters to be associated with the command are entered following the 
command verb or the keyword SLAVE, separated by commas. 

The keyword SLAVE is not referenced in the following command 
descriptions. Unless specifically disallowed, the command may be 
entered to be processed in the slave partition by including the keyword 
following the command verb. 
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CANCEL Command 



The CANCEL command should be used to terminate a Special Real Time 
Operating Sys tem job. 

The format of the command and its operands is: 



CANCEL 

Informs the input message processing routine that this reply is to 
cancel the Special Real Time Operating System jobstep for which this 
reply is outstanding. 

DUMP 

Cancel Special Real Time Operating System with a dump. The ABEND 
(dump) code is a user 122. 

NODUMP 

Cancel the Special Real Time Operating System without a dump. The 
ABEND code is a user 222. 

Comments 

Operator explanation as to reason for cancelling the Special Real 
Time Operating System. MESSAGE 60 will be issued, before cancelling 
the Special Real Time Operating System, containing the comment. The 
maximum length of the comment is 80 characters. 
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REPORT Command 

The REPORT command is used to control the execution of the Report Data 
output facility of the Special Real Time Operating System. The format 
of the REPORT command is: 



[ , input ddnanie, input ddname, . . . ] 
REPORT 

Informs the input message processing routine that this reply is for 
the Report Data Output Facility. 

NEW 

Report Data Output Facility will begin writing data at the beginning 
of the output data set. 

ADD 

Report Data Output Facility will begin writing data at the end of 
the output data set. 

Output ddname 

A ddname which points to a QSAM data set to be used as an output data 
set. The record length of the data set must be equal to or greater 
than the maximum record length of the input data sets. 

Input ddname 

A ddname which points to a QSAM data set to be used as an input data 
set. A maximum of 10 input DDNAMES may be specified. 
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r XX, REPORT 




DFEC Command 



The DREC command is used to control the execution of the Special Real 
Time Operating System Data Record and Playback function. The format 
of the DREC Command is: 



DREC 

Inform the input message processing routine that this reply is to 
initialize data recording. 

ENABLE Initialize data recording. 

DISABLE 
Deinitialize data recording. 

ADD 

Add the following ID'S to the data recording table. 
DEL 

Delete the following ID'S from the data recording table. 
ALL 

Enable all data recording IDs. 
ID 

Three digit hex numbers (001-FFF) that must be used in recording data 
as (enable ID' s) - 




, DISABLE 



, ENABLE 



, ADD 

,DEL ,ID, ID, ID 

.ALL 
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DDSCNTRL Command 

The DDSCNTRL Command is used to control the functions of duplicate data 
set support. The format of the DDSCNTRL command is: 



r XX. DDSCNTRL { , XXXXXXXX j 



The DDSNAME specified (or defaulted) on the DDSNAMES input control 
card which declared this duplicate data set. 

TAKE 

Causes the backup to be taken out-of-service, 

REPLACE PRIMARY WITH YYYYYYYY 
Causes the primary to become the backup (still in service) , and sets 
the data set with DDNAME YYYYYYYY to become primary. (YYYYYYYY will 
default to the old backup.) This function requires that the DDS DCBs 
be closed. 

CREATE 

Causes the primary to be copied track-by- track onto the backup, and 
sets the backup to be in-service (requires backup to be out-of-service 
on request) . 

SWITCH 

Causes the backup to become the primary and sets the primary as the 
backup out-of-service. (Requires backup to be in-service on request) . 

STATUS 

Prints a message (#56) stating primary and backup DDNAMES, and if 
backup is o ut-of-service. 

COMPARE 

Invoke the lEBCOMPR utility against ddnamel and ddname2. ddnamel 
will default to the primary DDNAME and ddname2 will default to the 
backup DDNAME. 



( , TAKE 

i, REPLACE [PRIMARY WITH YYYYYYYY] 
I , SWITCH 
I , CREATE 

(, STATUS r [ddnamel] [,ddnaine2]l 
(.COMPARE 
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DLHP Command 



The DIMP Command controls the operation of the Dynamic Load Module 
Purge feature of the Special Real Time Operating System. It permits 
the system operator to cause a load module to be deleted from virtual 
storage which has been loaded by the Special Real Time Operating System 
task management in response to PATCH requests. 

The format of the command and its operands is: 

r XX, DLHP, time, module-name, module-name. .. 

DLMP 

This input command is for the dynamic load module purge feature, 
time 

Decimal integer value between 0 and 1200; time in seconds that the 
DLMP feature will wait to allow other tasks to complete execution of 
the specified load modules. If time is omitted, a default value of 
2 seconds will be used. 

module name 

Name of the load module (s) that is to be purged from virtual storage. 
Up to 10 module names, separated by commas, may be specified in one 
request . 
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MSGRC COMMAND 



The MSGRC command is used to place a system message routing code in or 
out of service, determine the status of one or more routing codes, or 
change the alternate routing code. 



MSGRC 

Informs the input message processing routine that this reply is for 
the Message Routing Code Status Change Facility. 

Note: This command should not be entered in the SLAVE partition. 

rc 

Routing code, 

0 

This parameter is 0 if STATALL is specified. 

IN 

Place RC in service. 

OUT 

Place RC out of service. 

STATUS 

Display the status, via a system message, of the specified routing 
code (RC) . 

STATALL 

Display the status, via a system message, of all the routing codes in 
the system. 

al trc 

This parameter is recognized only if IN or OUT is specified. 

altrc is the routing code to which messages are directed should the 
primary routing code be out of service or the output operation fail. 
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r xx. MSGRC, 




IN 
OUT 
' STATUS 
' STATALL 



[ , altrc] 



QS COMMAND 



The QS command is an IMP command which may be used to display or alter 
the status of queue holders and queue processors. The format of the 
command and its operands is: 

iQPnn ' 
ALLQP 
na me ► 
ALLQH , 
ALL , 



Where the first positional parameter, QS, is the input message 
processing command name for the queue status facility, the second 
positional parameter is a noun used to identify the queue holders, 
queue processors, or independent task, the third positional parameter 
is a verb used to specify the primary action to be taken, and the fourth 
positional parameter is a verb used to specify the secondary action to 
be taken. The first three positional parameters are required. The 
fourth positional parameter is optional. 

QPnn 

The numberic value, nn, of this noun identifies a specific queue 
processor to be serviced on this command. The queue processor is 
identified by the numberic value specified on the QP statement in the 
SYSIHIT input stream. This ID has a range 00 to 99. Two characters 
must be supplied. 

ALLQP 

This noun is used to indicate that all queue processors are to be 
serviced on this command. 

name 

The 1 to 8 character name of this noun idnetifies a specific queue 
holder or independent task to be serviced on this command. The queue 
holder is identifed by the name specified on the QH statement in the 
SYSINIT input stream or an independent task by the name specified by 
the PATCH which created it. 

ALLQH 

This noun is used to indicate that all queue holders are to be serviced 
on this-command. 

ALL 

This noun is used to indicate that all queue holders, queue processors, 
and independent tasks are to be serviced on this command. 

SEQ 

This verb is used to request that work queued to the specified queue 
holder (s) be processed sequentially, (i.e., whenever work has been 
selected by a queue processor from a sequential queue holder, no other 
queue processor may select work from that queue holder until that work 
has been completed). Entry of this command will have no effect on 
any work that has already been selected by any queue processors. 

NONSEQ 

This verb is used to request that work queued to the specified queue 
holder (s) be processed n on- sequent ia 11 y (i.e., two or more queue 
processors may process wofJc from that queue holder concurrently,). A 
NONSEQ QS command will have no effect on any work that has already 
been selected by a queue processor. 



SEQ 

NONSEQ 
HOLD 
REL 

NOPATCH 
STATUS 
XREF 



[ , PURGE] 
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HOLD 

This verb is used to request that the specified queue holders, queue 
processors and/or independent tasks be held. As a result, no work 
may be selected from the specified queue holder (s) by any queue 
processor, the specified queue processor (s) will be prohibited from 
selecting work from any queue holder and specified independent task(s) 
will be prohibited from starting processing for any work that may be 
queued. Work may be added to the specified queue holder (s) or 
independent task (s) until the maximum queue length has been reached. 
A HOLD QS command will have no effect on any work that has already 
been selected for processing. 

REL 

This verb is used to release the work from the HOLD state the specified 
queue holders, queue processor and/or independent tasks for normal 
processing. A REL QS command will have no effect on any work that 
has already been selected by a queue processor. 

NOPATCH 

This verb is used to request that the specified queue holder (s) or 
independent task(s) to not accept additional PATCHes. Any PATCHes 
executed to a queue holder or independent task in a NOPATCH state will 
be rejected and condition code 6 will be returned to the user. Any 
work previously queued to the specified queue holder (s) and/or 
independent task (s) will be processed normally and will not be effected 
by a NOPATCH QS command, 

PATCH 

This verb is used to request that the specif eid queue holder (s) and/or 
independent task (s) may now accept PATCHes. 

STATUS 

This verb is used to request that the current status of the specified 
queue holder (s) , queue processor (s) and/or independent task (s) be 
displayed. This information is output as message 862 and includes: 
TCBX name, element type (QP, QH or TSK) , PATCH/NOP ATCH status, HOLD/REL 
status, SEQ/NONSEQ status, current queue length and the character 'A' 
if the task for a QP or independent task is currently processing a 
work queue. 

XREF 

This verb is used to request that the current status of the specified 
queue holder (s) , queue processor (s) and/or independent tasks to be 
displayed. This information includes message 862 as defined for the 
STATUS verb and in addition, message 863 will be output one or more 
titaes for each queue holder and/or queue processor specified. It 
includes, for a queue holder, the names of the queue processors which 
may select work from it and for a queue processor, the names of the 
queue holders from which it may select work. 

PURGE 

This verb may be used in conjunction with any primary verb to request 
that any work previously queued to the specified queue holder (s) and/or 
independent task (s) be purged by a PORGEHQ macro. A PURGE command 
will have no effect on any work that has already been selected by a 
queue processor. 
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STAE COMMAND 



The STAE command may be used to suppress system ABEND dumps for all or 
selected load modules. 



The format of the command and its operands is 



r XX, STAE 



^rDUMP 
,NODUMP 
,ONEDOMP 
,STEP 
OPTION 



y modenamel . . , modname n 



STAE 

Is a required positional operand which informs the input message 
processor that his reply is for the Dump/No Dump facility. 



DUMP 

Allow a dump to be taken for these modules (provided there is a 
SYSODUMP or SYSABEND DD statement). 

NODUMP 

Suppress a dump from being taken for these modules. 
ONEDUMP 

Allow one dump to be taken for these modules (provided there is a 
SYSUDOMP or SYSABEND DD statement) but suppress any additional dumps 
for that module. 



STEP 

ABEND the job step if one of these modules ABEND. 
OPTION 

Allows the operator to choose whether or not to take a dump following 
an ABEND of these modules. The operator is informed of the ABEND via 
a WTQR (message 850) and must reply 'YES' to receive the dump. If no 
reply is issued in five minutes, the dump is automatically suppressed. 

modnamel , . . . , modname n 
Is used to indicate the load module(s) that are to be covered by the 
specified option. A maximum of 10 load module names may be specified 
on any one reply- Null fields (double commas) will not be accepted. 

If no load module names are specified, the mode defined by the previous 
parameter will apply to all load modules. 
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STOP Command 

r XX, STOP 
STOP 

Cancel the Special Real Time Operating System without a dump. The 
ABEND code is a user 222. 
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CONTROL CARD IHIIQMATIQN 

The format of the Special Real Time Operating System control statements 
is very similar to the format of JCL statements. That is, there are 
four standard fields in the card. They are: 

LABEL OPERATION OPERANDS COMMENTS 

where: LABEL 

Is the control statement label and must begin in column one. If 
column one contains an asterisk (*) , the entire card is a comment 
card. The LABEL cannot exceed eight characters and must be separated 
from the OPERATION by at least one blank. The LABEL field is 
optional. 

where: OPERATION 

Is the type of action that the card represents. This field must 
contain one of the following: 

QP 
QH 

PATCH 

WAIT 

RESTART 

TCB 

GETWA 

CBGET 

ABEND 

MASTEB 

SLAVE 

DBREF 

STAEX 

The OPERATION field must be separated from the LABEL (if any) and 
OPERANDS by at least one blank. If no LABEL exists the OPERATION 
must not start in column one. The OPERATION field is required. 

where: OPERANDS 

The OPERANDS field is required for all OPERATION types except ABEND 
and must begin on the same card as the OPERATION, Each OPERATION 
has unique OPERANDS (see System Initialization) . The OPERANDS must 
be separated from the OPERATION and COMMENTS by at least one blank. 
There is a limit of 255 OPERAND characters for one OPERATION. 

where: COMMENTS 

The COMMENTS are optional and there is no limit to the length of 
COMMENTS allowed. The COMMENTS must be separated from the OPERANDS 
by at least one blank. 



CONTINUATION 

Control cards may be continued. Continuation is requested by 
Continuation is requested by ending the OPERAND'S field with a comma 
or putting a nonblank in column 7 2, or both. If the OPERANDS are 
completed and COMMENTS are to be continued, column 72 must be nonblank. 
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An example of valid continuations follows: 

COL 72 

PI PATCH EP=TEST, * 

TASK=TEST 

P2 PATCH EP=TEST, 

TA3K=TEST 

P3 PATCH EP=TEST TEST PROGAM* 

AND RETURN 

Continuation cards must begin in column 16. PATCH cards with PARAM 
data containing blanks within quotes may be continued to the next card. 
The continuation is assumed to start in column 16. 

EXAMPLE : 

COL 72 

PTCH PATCH EP=TEST, PARAH= fC ABCbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb* 

bbbbbbbbbXTZ •) 

COL 16 

The PARAM data would be 

' ABCbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbXrZ' 



TWOzEARTITION OPERATION 

The presence of a MASTER or a SLAVE statement in the input stream 
signifies two-partition operation. When this occurs, the first job 
started will issue the message DPP046I and will repeat the message at 
one-minute intervals until the other job has started. The operator 
should ensure that the job names of the SLAVE corresponds to the na me 
given on the MASTER card by the S LAVE= jobname operand and that the 
jobname of the MASTER corresponds to the name given on the SLAVE card 
by the MASTER = jobname operand. If the MASTER job terminates, the SLAVE 
will also be terminated with a USER 41 ABEND coda. However, if the 
SLAVE job terminates and the MASTER is still executing, the SLAVE job 
may be restarted in the same or another partition. 

Note: The Special Real Time Operating System job should not be 

terminated by a CANCEL JOBNAME command as STAE processing will 
be bypassed. As a result, the SLAVE will not be terminated when 
the MASTER ends, and the SLAVE will not restart if an attempt 
is made to restart it. 



FMLOVER/MSTART OPERATION 
SINGLE CPU ENVIRONMENT 

The operator may cause a RESTART by dialing the device address which 
contains the RESTART data set into the »LOAD UNIT ADDRESS' switches of 
the CPU and depressing LOAD (IPLing) . This operation will be successful 
only if a RESTART data set had been previously written by a RESTART 
WRITE statement. The data set would have been written to the data set 
allocated to the DPPFAIL DD card. If copies had been made of the 
DPPFAIL data set, a RESTART could be caused by the operator IPLing the 
DA device containing the DPPFAIL data set or a copy of the DPPFAIL data 
set . 
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SINGLE CPU ENVIRONMENT WITH CONTINUOUS MONITOR 



The continuous monitor is a program which monitors the online CPU and, 
if any failures are detected, recommends a RESTART. The RESTART is 
recommended by message DPP098. When this message is issued, the operator 
must RESTART the system as described above. 



TWO-CPU ENVIRONMENT WITH CONTINUOUS MONITOR AND PROBE 

With the continuous monitor operating in the realtime CPU and the PROBE 
in the backup CPU, no operator intervention is reguired on a FAILOVER 
condition. The FAILOVER is initiated by the PROBE when an error 
condition is detected. If, however, the system has a Computer Status 
Panel installed, and the status panel is not switched to auto mode, 
the operator must decide whether to cause a FAILOVER to the backup CPU 
or to RESTART in the online CPU. He must then initiate the action by 
depressing the SELECT button for the CPU which he wants to execute as 
the online CPU. 



NORMAL TERMINATION PROCEDURES 

The Special Real Time Operating System should be terminated by replying 
to the Input Message, Processor's outstanding message with a CANCEL or 
STOP command. This command and its operands are documented earlier in 
this chapter- The Special Real Time Operating system should not be 
terminated by the 0S/VS1 CANCEL command which causes the STAE processing 
for the job step task to be bypassed. The effect of bypassing the STAE 
may be to leave certain system functions in a condition which will 
degrade subsequent system operation. If it is necessary to use the 
0S/VS1 CANCEL command, the 0S/VS1 system should be re-IPLed at the 
earliest convenience. 

The Special Real Time Operating System should be terminated with the 
OS CANCEL command only as a last resort. Terminating the Special Real 
Time Operating System with the OS CANCEL command bypasses STAE cleanup 
routines and will not cause the SLAVE job to be terminated when the 
MASTER ends and the MASTER may cause processing errors for any job that 
starts in the partition the SLAVE ended in. If a SLAVE job is 
terminated with the OS CANCEL command, it will not be able to restart. 

If it is necessary to use the OS CANCEL to terminate a MASTER job, the 
SLAVE must also be terminated with the OS CANCEL command. 
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THE SPECIAL REAL TIME OPE RATING S YSTEM MMD CODES 
USER 001 Issued by: DPPITIMI 

Explanation: An invalid TCBX address was found in the job step TCBOSER 
field. 

Action: Restart the system. 

USER 002 Issued by: DPPITIMI 

Explanation: An invalid SCVT or XCVT address was found in the job 
step control block chain. 

Action: Restart the system. 

USER 003 Issued by: DPITIMI1 

Explanation: The time-of-day (TOD) clock was not operational. 
Action: Probable hardware failure. 

USER 004 Issued by: DPPITIMI 

Explanation: Time array - DPPCTIMA - was not found in the data base. 

Action: DD card DBINIT must allocate a data base data set that 

contains a DPPCTIMA array, 

USER 010 Issued by: DPPIDBAS 

Explanation: An invalid TCBX address was found in the job step TCBOSER 
field. 

Action: Restart the system. 

USER Oil Issued by: DPPIDBAS 

Explanation: An invalid SCVT or XCVT address was found in the job 
step control block chain. 

Action: Restart the system. 

USER 012 Issued by: DPIDBAS 1 , DPI DBAS 2, or DPIDBAS3 

Explanation: Data base initialization was unable to open one of the 
following data sets: 

DDname - DBINIT 

DDname - DBINIT2 
or a user specified data base data set. 

Action: DD cards must exist for DBINIT and DBINIT2 and 

user-requested data base sets Be sure that the data set 
exists. 

USER 013 Issued by: DPIDBAS1 
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Explanation: Data base initialization was unable to find member aiNIT 
in the DBINIT data set via BLDL. 

Action: DD card DBINIT must allocate the correct data base data 

set containing member name SINIT. 



USER 020 Issued by: DPPMINIT 

Explanation: The online message handler initialization was unable to 
OPEN the message data set DCB. 

Action: The job's JCL must contain a DD statement with DD name 

MSGDS. 



OSER 022 Issued by: DPPINIT1 

Explanation: This ABEND was requested by the user through the presence 

of an ABEND statement in the SYSINIT input stream- 
Action: None. 



USER 023 Issued by: DPPMINIT 



Explanation: The online message handler initialization could not find 
the message routing code array DOMXSMRC in the data 
base . 



Action: The array should be generated at the Special Real Time 

Operating System SYSGEN time by the use of the MSGRC 
macro. DMINIT must have a DD card that allocates the 
correct data set. 



USER 030 Issued by: DPPINIT 

Explanation: The Special Real Time Operating System initialization 
(DPPINIT) was not running under the job step task TCB. 

Action: Program DPPINIT cannot be attached, but must be the job 

step task. 



USER 031 Issued by: DPPINITI 

Explanation: A PATCH macro was executed in response to a PATCH 

initialization card. The return code from the PATCH 
macro was greater than H (i.e., the PATCH failed). 



Action: 



At the time of the dump. Register 3 contains the address 
of a PATCH control block. Four bytes past that address 
is the address of the PATCH PROBL and X'14' bytes past 
that address is the PATCH SUPL. The first 9 bytes of 
the SUPL contain the task name and the second 8 bytes 
contain the entry point name specified on the PATCH card 
for which the failure occurred. Register 15 contains 
the PATCH return code. Make appropriate corrections 
and retry. 



USER 032' Issued by: DPPFIXFR 
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Explanation: An invalid address range was passed to be either fixed 
in real storage or unfixed. 

Action: Correct the address range and retry, ensure that array 

DPPXFIX is valid. 



USER 033 Issued by: DPINIT3 

Explanation: Initialization was unable to get enough control block 
(CBGET) storage in which to create a TCBX at 
initialization time. 

Action: Increase the CBGET storage with a CBGET statement in 

the SYSINIT input stream and retry. 



USER 034 Issued by: DPINIT05 

Explanation: A syntactical error was detected on one or more of the 
initialization input (SYSINIT) statements. 

Action: Correct the statement (s) in error and retry. 



USER 035 issued by: DPPINIT1 

Explanation: A pre- WRITE RESTART program which was PATCHed as a result 
of a PATCH statement in the SYSINIT input stream 
completed and returned with a non-zero POST code. 

Action: Correct the failing program and retry. 

USER 036 Issued by: DPINIT5 

Explanation: On a two-partition run, a MASTER or SLAVE partition had 
been posted by the other partition; however, the 
corresponding jobname could not be found. 

Action: Correct the MASTER or SLAVE card so that the operands 

give the exact jobname of the job in the corresponding 
partition. 



USER 037 Issued by: DOMIRFLV 

Explanation: During an attempt to write a FAILOVER data set 

(WTFAILDS) , the SLAVE partition could not be found. 

Action: If the SLAVE job has ABENDED or terminated, fix the 

failure and resubmit the run. 



USER 038 Issued by: DOMIRFLV 

Explanation: Multiple simultaneous attempts were made to write a 
FAILOVER data set (WTFAILDS) from the same job. 

Action: Correct the programs. 



USER 039 Issued by: DOMIRFLV 
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Explanation : 



The WTFAILDS macro was issued by a non-real time job. 



Action: 



The WTFAILDS macro must be issued by a Special Real Time 
Operating System job. 



USER 040 Issued by: DPINIT05 

Explanation: The SYSINIT DCB could not be opened, no SYSINIT DD card 
was provided or a SYSINIT stream was processed that did 
not contain a PATCH statement. 

Action: The job's JCL must contain a SYSINIT DD card and at 

least one PATCH statement in the input stream. 



USER 041 Issued by: DPPISTAE 



Explanation : 



Action: 



The SLAVE job is abnormally terminated with this code 
when the MASTER job step terminates. The SLAVE cannot 
continue to run because it does not have full Special 
Real Time Operating System services. 

Restart MASTER and SLAVE jobs. 



USER 042 Issued by: DPINIT5 



Explanation : 



Action: 



During the restart of a SLAVE job, the initialization 
routine could not locate the job named on the MASTER= 
operand of the SLAVE statement. 

Correct the SLAVE statement and retry. 



USER 043 Issued by: DPINIT5 



Explanation : 



Action: 



The SLAVE job was being restarted after a failure; during 
initialization the SLAVE initialization found the MASTER 
job step to be terminating. 

Restart both MASTER and SLAVE jobs. 



USER 044 Issued by: DPINIT5 



Explanation : 



Action: 



An attempt was made to restart a SLAVE for a MASTER 
which already had a SLAVE job executing. 

Verify the jobname on the SLAVE MASTER- jobnarae control 
statement. It should have a jobname for a MASTER job 
step that does not have a SLAVE job currently executing, 



USER 045 Issued by: DPPINITI 



Expla nation : 
Action: 



A RESTART Statement was processed in the input stream 
which requested the CANCEL function. 

None. 



USER 046 Issued by: DPPINITI 
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Explanation: The maximum size GETWA space allocated was not sufficient 
to satisfy the requirements of the Special Real Time 
Operating System. A GETWA size of 1024 bytes is 
required. 

Action: Allocate a larger GETWA size (1024 bytes) on the GETWAS 

parameter of the VS macro and regenerate the system or 
specify appropriate GETWA sizes on the GETWA statement 
in the SYSINIT input stream and rerun the job. 



USER 050 Issued by: DPXDBIN6 



Explanation: The offline utility program was unable to OPEN the 
initialization data set for DD name DBINIT. 



Action : 



The offline utility JCL must include a DBINIT DD card. 



USER 051 Issued by: DPXDBIN4 

Explanation: The offline utility program had an error while attempting 
to STOW initialization member SINIT. 

Action: Retry. 



OSER 052 Issued by: DPXDBIN1 

Explanation: The offline utility program was unable to obtain 

initialization member aiNIT from the initialization data 
set. 

Action: Retry run. 

OSER 053 Issued by: DPXDBIN2 

Explanation: A loggable array was created which named a log array. 
The named log array could not be found. 

Action: Recompile the loggable array to have the log array 

recrea ted. 



USER 054 Issued by: DPIDBAS3 

Explanation: A BLDL error was encountered while attempting to read 
the PDS directory entry for a loggable array. 

Action: Recompile to loggable array to have the log array 

recreated. 



OSER 055 Issued by: DPPXDTIL 

Explanation: The assembler encountered an error and returned an error 
code greater than 16. 

Action: Correct the problem indicated by the assembler output 

and retry the job. 



USER 064 Issued by: DPPTETXR 
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Explanation: Program DPPTETXR has been entered under a TCB which is 
not a job step TCB, 

Action: If a program is linking to DPPTETXR, correct and retry, 

otherwise retry. 



USER 065 Issued by: DPPTDSVC 

Explanation: A DPATCH=I was issued for the specified task so the 
Special Real Time Operating System task management 
terminated it with this code. 

Action: None. 



USER 071 Issued by: DPPXDPB 

Explanation: Data playback was unable to OPEN the data playback DCB. 

Action: A DD card named DPBIN must exist if data playback is to 

be used. 



USER 072 Issued by: DPPXDPB 

Explanation; The BLKSIZE and LR ECL on the DPBIN DD card is smaller 
than the maximum BLKSIZE and LRECL used when the data 
recording/playback data set was defined and/or when data 
was recorded on the data recording/playback data set. 

Action: The BLKSIZE and LRECL on the DPBIN DD card must be equal 

to the maximum BLKSIZE and LRECL on the data 
recording/playback data set. 



USER 080 Issued by: DPPSINIT 

Explanation: A bad card was found in the DDSCTLIN input stream. 
Action: Correct control card and retry. 



USER 081 Issued by: DPPSCHCK 

Explanation: User received software I/O error but did not specify a 
SYNAD exit routine for a DDS data set. 

Action: None* 



USER 122 Issued by: DPPXKILL, DPPXIHPW 

Explanation: The job step task has been ABENDed due to the 
CANCEL, DUMP request. 

Action: None. 



USER 222 Issued by: DPPXKILL 

Explanation: The job step task has been ABENDed due to a 
CANCEL, NODUMP request. 
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Act ion : 



None. 



SYSTEM 4xx Issued by: A DSER-GEN ERATED SVC 

Explanation: A user program made an invalid SVC The request was for 
the SVC number xx. xx is the hexadecimal number of the 
SVC which was issued. 

Action: Correct program and ensure that a valid SVC request is 

made. 



SYSTEM 6xx Issued by: A USER-GEN EB AT ED SVC 



Explanation: A user program made a Special Real Time Operating System 
SVC request from a non-Special Real Time Operating System 
job step task. The SVC requested is indicated by xx. 
xx is the hexadecimal number of the SVC which was issued. 



Action: Check the user program and be sure that services which 

are not available to a non-Special Real Time Operating 
System task are not requested by a non-Special Real Time 
Operating System task. 
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THE SPECIAL REAL-TIME OPERATIKG SYSTEM ONLINE MESSAGES 

DPP009I POST-RESTART DATA BASE AND PRE-RESTART DATA BASE ARE 

DIFFER ENT 

Routing code: 1 

Message issued by segment: DPPDWRST 

Explanation: One or more data base arrays have been recompiled onto 

the DBINIT data set that is online at restart time since 
the restart data set was written or a different data 
base is being referenced. Results are unpredictable 
and continued operation may or may not be successful. 

Response: None. 

DPP010I Time date DPPTETXR * EXCEPTL CONDITION BAD WQE XXXXXXXX 

Routing code: 2 

Message issued by segment: DPPTETXR load module DPPTETXR 

Explanation: A subtask running the PATCH monitor DPPTPMON terminated 
and caused the End-of- Task-Exit Routine to be entered. 
The address of the current WQE XXXXXXXX was found to be 
invalid. Therefore, DPPTETXR cannot perform its full 
service which causes CB-GET storage to be lost. 

Response: None, 

DPP011I time DPPTETXR * ABEND IN MESSAGE OUTPUT TASK 

Routing code: as defined through SYSGEN 

Message issued by segment: DPPTETXM load module DPPTETXR 

Explanation: The Special Real Time Operating System message output 
task DPPMMSG1 ABENDed and caused the End-of-Ta sk-Exi t 
Routine to be entered. This message is issued through 
a WTO macro^ because the message output task is not 
available to print /display it. 

Response: None. 

DPP012I time date DPPTETXR * TASK TTTTTTTT ENDED WITH CC XXXXXXXX 

or 

DPP012I time date DPPTETXR * TASK TTTTTTTT ENDED WITH CC XXXXXXXX 

WQID NNN PATCH EP EEEEEEEE 

Routing code: 2 

Message issued by segment: DPPTETXR load module DPPTETXR 

Explanation: The special Real Time Operating System task tttttttt 
terminated and caused the End-of -Task-Exit Routine to 
be entered- The TCB completion code field was X,XXXXXXX. 

If the address of the current WQE is available to the 

routine, it also displays the ID NNN and the EP name 

EEEEEEEE that was specified when the originating PATCH 
was issued^ 



OPERATOR'S REFERENCE 4-23 



Response: 



None. 



DPP013I time date DPPTETXR * EXCEPTL CONDITION BAD TCBX XXXXXXXX 

Routing code: 2 

Message issued by segment: DPPTETXR load module DPPTETXR 

Explanation: A subtask running the PATCH monitor DPPTPMON terminated 
and caused the End-of-Task-Exit Routine to be entered. 
The address of the TCB extension XXXXXXXX, which is 
contained in the TCB USER field, was found invalid. 
Therefore, DPPTETXR cannot perform its full service. 
This causes loss of CB-GET storage for TCBX, WQE chain, 
and LCB chain and may also result in system degradation. 

Response: None. 



DPPOmi time date DPPTPMON * TASK TTTTTTTT EP EEEEEEEE WQID NNN 

NOT FOUND BY BLDL 

Routing code: 2 

Message issued by segment: DPTPM0N3 load module DPPTPMON 

Explanation: A PATCH macro was issued for task TTTTTTTT that specified 
an ID of NNN and an EP name of EEEEEEEE. The PATCH 
monitor DPPTPMON issued BLDL for the given EP name and 
received a return code of 4, which indicates that the 
module was not found- If an ECB = address was specified 
with PATCH, that ECB is posted with a completion code 
of 48 in the high order byte. 

Response: None. 



DPP015I 



time date DPPTPMON * TASK TTTTTTTT EP EEEEEEEE WQID NNN 
BLDL I/O ERROR 



Routing code: 2 

Message issued by segment: 



DPTPM0N3 load module DPPTPMON 



Explanation : 



Response : 



A PATCH macro was issued for task TTTTTTTT that specified 
an ID of NNN and an EP name of EEEEEEEE. The PATCH 
monitor DPPTPMON issued BLDL for the given EP name and 
received a return code of 8, which indicates that a 
permanent I/O error was detected when the 0S/VS1 system 
attempted to search the directory. If an ECB= address 
was specified with PATCH, that ECB is posted with a 
completion code of 48 in the high order byte. 

None . 



DPP016I 



time date DPPTPMON * TASK TTTTTTTT NOT FOUND ON ACTIVl 
CHAIN 



Routing code: 2 

Message issued by segment: 



DPTPM0N1 load module DPPTPMON 
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Explanation: The PATCH monitor attempted to remove a TCB extension 

from the active task chain and could not find it on that 
chain. 



Response: None. 



DPP017I time date DPPTSMON * NO LOAD REQUEST FOUND 

Routing code: 2 

Message issued by segment: DPTSBONI load module DPPTSMON 

Explanation: The system monitor DPPTSMON was posted and attempted to 
service a request for LOAD of a reentrant load module, 
which is indicated by a flag in the TCBX. However, when 
trying to find the LCB for which the LOAD was requested, 
no LCB with the LOAD request flag turned on could be 
found on the TCBX-LCB chain. DPPTSMON POSTs the PATCH 
monitor to continue its processing. 

Response: None. 



DPP018I time date DPPTETXR * TASK TTTTTTTT EP EEEEEEEE WQID NNN 

DID NOT RETURN TO DPPTPMON 

Routing code: 2 

Message issued by segment: DPPTETXR load module DPPTETXR 

Explanation: A PATCH macro was issued for task tttTTTTT that specified 
an ID of NNN and an EP name of EEEEEEEE. 

The PATCH monitor scheduled that WQE and passed control 
to the specified module, which did not return control 
to DPPTPMON as required in the Special Real Time 
Operating System environment. 

The module returned control to 0S/VS1 which scheduled 
the End-of -Task-Exit routine. 

If an ECB= address was specified with PATCH, the ECB is 
posted with 4C in the high order byte. 

Response: Check the module for possible 

SVC 3 EXIT 
ABEND 0 
LINK 
XCTL 

Change to BR to return control to DPPTPMON. 



DPP019I time date DPPTDLMP * TIME VALUE TOO HIGH REQUEST 

ABANDONED 

Routing code: 2 

Message issued by segment: DPPTDLHP load module DPPTDLMP 

Explanation: On an input command DLMP to Dynamic Load Module Purge, 
the time specified was not between 0 and 1200 seconds. 

Response: Use a valid time value and issue the command again. 
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DPP020I time date DPPTDLMP * LOAD MODOLE PURGE ENTERED. 

Routing code: 2 

Message issued by segment: DPPTDLMP load module DPPTDLMP 

Explanation: A valid DLHP command has been accepted and the Dynamic 
Load Module Purge function is in progress. 

Response: None, 

DPP021I time date DPPTDLMP * MODULE HHMMMMMM DID NOT COMPLETE 

IN TIME FOR PURGE 

Routing code: 2 

Message issued by segment: DPPTDLMP load module DPPTDLMP 

Explanation: A DLMP command vas issued but the module HMHHHHHH did 
not finish executing before the time specified on the 
command had expired. Message DPP022I will follow to 
indicate the end of the purge function. 

Response: One of the following: 

• Retry command after module completes execution, if known. 

• Try again using a higher time value- 

• If module MMMMMHHM is a long running program, it may be impossible 
to purge it at all. 

• If module HHMHMHHM is either in an endless loop or in a HAIT state, 
it may be impossible to purge it. 

DPP022I time date DPPTDLMP * LOAD MODULE PURGE ABANDONED 

Routing code: 2 

Message issued by segment: DPPTDLMP load module DPPTDLMP 

Explanation: A DLMP command vas issued but could not be completed. 

This message follows other explanatory messages and 
indicates the end of the purge function. 

Response: Check for previous messages DPP021I. 

DPP023I time date DPPTDLMP ♦ LOAD MODULE PURGE COMPLETE 

Routing code: 2 

Message issued by segment: DPPTDLMP load module DPPTDLMP 

Explanation: A DLMP command was issued and executed successfully. 

This message indicates the end of the purge operation. 

Response: None. 

DPP024I STAE OPTION XXX IS yyy zzz 
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Routing code: 2 



Message issued by segment: DPPTIMPS 

Explanation: This message is issued to reply to the Input Message 
Processor of the form: 

P XX,STAE,... 

It is used to notify the operator of the results of the 

STAE command. xxi is the option selected on the STAE 

command, yyy is an indication as to whether the STAE 

command was valid (yyy = IN EFFECT) or erroneous (yyy 
= INVALID) . 

2ZZ further defines the result of the STAE command: 

ZZZ = FOR ALL LM. ALL PREVIOUS STAE REQUESTS ARE 
CANCELLED indicates that the general STAE command was 
accepted- 

ZZZ = FOR VALID LM NAMES SPECIFIED ON THIS REQUEST 
indicates that the specified STAE command was accepted 
for all load modules specified unless one or more of 
the load modules names are rejected on a subsequent 
DPP025I message. 

zzz = THIS STAE REQUEST WILL NOT BE HONORED indicates 
that the STAE command option was neither "DUMP", 
"NODUMP", or "STEP". 

Response: If the STAE option was invalid, select either "DUMP", 

"NODUMP", "ONEDUMP", or "STEP" option and re-issue the 
comman d. 



DPP025I time LM NAME XXX - SPECIFIED ON STAE REQUEST IS INVALID 

AND WILL NOT BE PROCESSED 

Routing code: 2 

Message issued by segment: DPPTIMPS 

Explanation: One of the load module names specified on the previous 
STAE command was found to be invalid. Message DPP02UI 
was issued to notify the user of the option in effect 
as a result of that STAE command. Multiple DPP025I 
messages may be issued, one for each invalid load module 
name on that STAE command. 

Response: Ensure that all characters in a specified load module 

name are either alphanumeric or one of the special 
characters "$", "#", "3". The special character "?" 
may also be used to delimit the load module name. The 
first character of a load module name cannot be numeric. 
Re-issue the STAE command with the corrected load module 
names. 



DPP026I time INVALID IMP COMMAND 

Routing code: 1 

Message issued by segment: DPPXIHPP 
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Explanation: An invalid IHP command vas issued. 

Response: If the IHP comniand was misspelled, it should be reissued. 

If the specified IMP command was entered correctly, it 
is not known to the system. Therefore, the IMP command 
requested should be defined and added to the system. 



DPP027I time OPERATOR COMMAND NOT DUMP OR NODDHP - THE SPECIAL 

REAL TIME OPERATING SYSTEM NOT CANCELLED 

Routing Code: 2 

Message issued by segment: DPPXKILL 

Explanation: A cancel IMP command was issued which specified an action 
other than DUMP or NODUMP. 

Response: A cancel IMP command should be issued which specifies 

an action of DUMP or NODUMP or the parameter should not 
be specified. If no parameter is specified, the IMP 
command parameter will default NODUMP. 



DPP028I time TASK - DPPSAMPl WAS ENTERED AT ENTRY POINT DPPSAMP1 

Routing Code: 1 

Message issued by segment: DPPSAMPl 

Explanation: Test message issued by the Special Real Time Operating 
System sample program. 

Response: None. 



DPP029I time date RC = hhh cccccccccccccccccccccc CONSOLE OS 

DESCRIPTOR AND ROUTING CODES xxxx ALTRC hhh 

Routing Code: 1 

Message issued by segment: DPPMMSGV 

Explanation: The message displays the status (In or Out of Service) 
of system messages console routing codes. The message 
is issued in response to an MSGRC IMP command. 

Response: None. 



DPP030I time date RC = hhh cccccccccccccccccccccc PROGRAM TASK 

NAME = tttttttt EPNAME = nnnnnnnn ALTRC = hhh 

Routing code: 1 

Message issued by segment: DPPMMSGV 

Explanation: The message displays the status (In or Out of Service) 
of system messages output program routing codes. The 
message is issued in response to an MSGRC IMP command. 

Response: None. 
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DPP031I 



time date KC = hhh cccccccccccccccccccccc OS DEVICE 
DDNAME « dddddddd ALTRC = hhh 



Routing code: 1 

Message issued by segment: 



DPPMMSGV 



Explanation: The message displays the status (in or Out-of-Service) 
of system messages OS DEVICE (printer, tape, etc. The 
message is issued in response to an HSGBC IMP command. 

Response: None. 



DPP032I 



time date RC = hhh cccccccccccccccccccccc DISPLAY FONC 
AREA = X ACCESS AREA ~ X ALTRC = hhh 



Routing code: 1 

Message issued by segment: 



DPPMMSGV 



Explanation: The message displays the status (In or Out of Service) 
of system messages display routing codes. The message 
is issued in response to an MSGRC IMP command. 

Response: None. 



DPP033I 



time INVALID REQUEST - ALTERNATE ROOTE CODE IS OOT OF 
SERVICE 



Routing Code: 1 

Message issued by segment: 



DPPMMSGV 



Explanation: 



Response: 



An MSGRC IMP command was issued that specified an 
alternate route code that is out of service. An MSGRC 
IMP command should be issued that specifies no alternate 
route code or one that specifies an alternate route code 
that is in service. An MSGRC IMP command with a STATALL 
parameter can be specified to determine that route codes 
are in or out of service. 

None. 



DPP034I time INVALID R] 

Routing code: 1 

Message issued by segment: 



IDE ST - ROOTE CODE = ALTERNATE ROOTE CODE 



DPPMMSGV 



Explanation : 



Response: 



An MSGRC IMP command was issued that specified the same 
route code in the primary and alternate route code 
parameters. 

An MSBRC IMP command should be issued that specifies 
different route codes for the primary and alternate 
route code parameters. 



DPP035I 



time ROOTING CODE NOT FOOND OR ACTION (STATUS STATALL, 
IN OR OOT) PARAMETER NOT SPECIFIED 
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Routing code: 1 

Message issued by segment: DPPMMSGV 

Explanation: An MSGRC IMP command contains a route code not in the 
system or ACTION parameter, STATUS - STATALL-IN-OOT, 
not specified. 

Response: The validity of the route code should be determined 

issuing an MSGRC IMP command with a ST AT ALL parameter 
or a valid action parameter (STATU S-STATALL-IN-OOT) 
should be specified- 

DPP036I DDSNAME = XXXXXXXX, COMPARE ENDED WITH I/O ERROR, RESULTS 

ON COMPRINT REPORT DATA SET 

Routing code: 3 

Message issued by segment: DPPSCMPR 

Explanation: If lEBCOMPR returns with a return code G.7. 4, this 
message is output. 

Response: None. 

DPP037I USER DATA 

Routing code: 2 

Message issued by segment: None. 

Explanation: This message is comprised of 50 characters of user data 
on which no translation is done. The data is output 
exactly as passed by the user. There is no use of this 
message by the released Special Real Time Operating 
System system. 

Response: None. 

DPP038I POSSIBLE SPECIAL REAL TIME OPERATING SYSTEM TIME ERROR 

- THE SPECIAL REAL TIME OPERATING SYSTEM TIME OF DAY 
HAS BEEN RECALCULATED 

Routing code: 2 

Message issued by segment: DPPCTIME or DPPCTIM2 

Explanation: The time interval between successive updates to the 

Special Real Time Operating System time array exceeded 
the allowable tolerance, so a new time was calculated. 

Response: None. 

DPP039I THE OS/SPECIAL REAL TIME OPERATING SYSTEM TIME CONVERSION 

FACTOR HAS BEEN UPGRADED 

Routing code: 2 

Message issued by segment: DPPCUPCF 
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Explanation: A time correction value has been passed to the Special 
Real Time Operating System time management services and 
the Special Real Time Operating System time and date 
have been updated accordingly. 

Response: None. 

DPP0U1I XXX HAS BEGUN PROCESSING SYSINIT INPUT STREAM 

Routing code: 2 

Message issued by segment: DPPINIT1 

Explanation: This message is used to notify the operator that the 
SYSINIT input stream is being processed. It is an 
indication that the Special Real Time Operating System 
has completed initialization. xxx - is used to identify 
the SYSINIT input stream. 

xxx = "SLAVE JOB" indicates the SLAVE partition SYSINIT 
input streams. 

xxx = "MASTER JOB" indicates the MASTER partition 
SYSINIT input stream. 

xxx = "SRTOS JOB" indicates the realtime partition 
SYSINIT input stream in a single partition 
environment- 
Response: None 

DPP0U2I BLDL FAILED FOR MODULE HMMMMHMM - RETURN CODE WAS 

CCCCCCCC 

Routing code: 2 

Message issued by segment: DDDIDFIX 

Explanation: The page fix routine had a load module fix request for 

module MMMMMMMM, a BLDL for the module failed, the return 
code Has CCCCCCCC. 

Response: Check array DPPXFIX and verify that the module to be 

fixed exists as a load module and the array is properly 
built. 

DPPOaai FIX FAILED FOR TTTTTTTTTT - NNNNNNNN - RETURN CODE WAS 

CCCCCCCC 

Routing code: 2 

Message issued by segment: DPPIPFIX 

Explanation: An attempt was made to fix virtual storage for TTTTTTTTTT 
- (load module, named array, numbered array) - named 
NNNNNNNN - the return code from the page fix routine 
was CCCCCCCC. 

Response: The contents of array DPPXFIX should be reviewed; the 

normal cause of this failure is too much real storage 
is becoming fixed. 
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Dppoaai 



TASK = TTTTTTTT - EP=EEEEEEEE WAS POSTED WITH A NONZERO 
POST CODE - ECB CONTENTS = CCCCCCCC 



Routing code: 2 

Message issued by segment: DPINIT11 

Explanation: Task named TTTTTTTT, with entry point named EEEEEEEE, 
was PATCHed by Special Real Time Operating System 
initialization. The task was PATCHed with the ECB= 
option and, at termination, the ECB had a non-zero 
completion code. The contents of the ECB were CCCCCCCC, 

Response: Notify the responsible programmer. 

DPP045I CONTROL STATEMENT ERROR DETECTED - RON ABORTED 

Routing code: 2 

Message issued by segment: DPINIT05 

Explanation: The SYSINIT input stream contained control statement (s) 
which were erroneous. The run is terminated. 

Response: Have the erroneous control statements corrected and 

resubmit the run. 



DPP046I MASTER OR SLAVE PARTITION WAITING FOR CORRESPONDING 

MASTER OR SLAVE TO BE INITIALIZED 

Routing code: 1 

Message issued by segment: DPINIT5 

Explanation: A job has been started whose SYSINIT stream contained 
a MASTER or SLAVE Statement. The job has reached a 
point in its initialization where it can go no further 
until its corresponding MASTER or SLAVE has been started, 
This message is issued at one-minute intervals until 
the corresponding MASTER or SLAVE job is initialized. 

Response: Start the corresponding MASTER or SLAVE job. 

DPP0U7I GETARRAY FAILED FOR DPPXFIX - RETURN CODE WAS CCCCCCCC 

- PAGE FFFFFFFF BYPASSED 

Routing code: 2 

Message issued by segment: DPPIPFIX and DPPDPFRE 

Explanation: A PATCH to DPPIPFIX was issued; however, array DPPXFIX 
was not located. The return code from the GETARRAY for 
array DPPXFIX was CCCCCCCC. The Function (FIX or FREE) 
was The Function (FIX or FREE) was bypassed. 

Response: Remove the PATCH to DPPIPFIX or be sure that array 

DPPXFIX exists in the data base being used (DBINIT and 
DBINIT2 cards) . 

DPP048I GETARRAY FAILED FOR TTTTTTTT - NNN - RETURN CODE WAS 

CCCCCCCC. 
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Routing code: 2 

Message issued by segment: DPPIPFIX 

Explanation: A PATCH was issued to DPPIPFIX. While processing array 
DPPXFIX, a fix request was found for ttTTTTTT (named 
array or numbered array) ^ a GETARRAY was issued to locate 
the named or numbered array NNNNNNNN. The GETARRAY 
failed with return code CCCCCCCC. 

Response: Check that the numbered or named array exists in the 

data base, or that array DPPXFIX is valid. 



DPP049I ITEM IIIIIIII IN ARRAY DPPXFIX COOLD NOT BE FIXED BECAUSE 

THE TYPE FIELD IS INVALID 

Routing code: 2 

Message issued by segment: DPPIPFIX 

Explanation: A PATCH was issued to DPPIPFIX; while processing array 
DPPXFIX, an Item IIIIIIII was found that contained an 
invalid fix type. 

Response: The only valid fix types are N, A and L. Have array 

DPPXFIX corrected. 



DPP050I time date DRECOUT DD CARD MISSING 

Routing code: 2 

Message issued by segment; DPPXRINT 

Explanation: Data recording initialization was unable to open the 

data recording DCB due to the absence of the DRECOUT DD 
statement in the job step JCL. 

Response: A DRECOUT DD statement should be added to the job step 

JCL. 



DPP051I time date DPBIN DD CARD MISSING 

Routing code: 2 

Message issued by segment: DPPXDPB 

Explanation: Data playback was unable to open the data playback DCB 
due to the absence of the DPBIN DD statement from the 
job step JCL- 

Response: A DPBIN DD statement should be added to the job step 

JCL. 



DPP052I PAGE FIX FUNCTION COMPLETE - ALL ITEMS WERE XXXXXX 

Routing code: 2 

Message issued by segment: DPPIPFIX 

Explanation: A PATCH was issued to DPPIPFIX. Array DPPXFIX was 

processed; when all processing had been completed, this 
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message was issued to say all ITEMS were XXXXXX - (FIXED 
or NOT FIXED) . 



Response: If all ITEMS were not fixed, a decision may be required 

whether to continue or terminate this run. 

DPP053I time date REPORT DATA OaTPOT FACILITY UNABLE TO OPEN 

SPECIFIED DATA SET 

Routing code: 2 

Message issued by segment: DPPXRPRT 

Explanation: Report Data output Facility unable to open specified DD 
statement due to the absence of the DD statement from 
the job step JCL. 

Response: A DD statement should be added to the job step JCL for 

each DD name passed to the Report Date Output Facility 
or the DD name that is not defined by a DD statement 
should not be passed to the Report Data Output Facility. 

DPP05UI WRITING OF FAILOVER DATA SET BYPASSED FOR RESTART OF 

SLAVE PARTITION 

Routing code: 2 

Message issued by segment: DPPINIT1 

Explanation: A MASTER and a SLAVE had been running, and the SLAVE 

terminated. The SLAVE is being restarted and its SYSINIT 
stream contains a RESTART WRITE statement. A failover 
data set had been written on the initial startup of the 
MASTER and SLAVE, so this function is bypassed. 

Response: None. 

DPP055I ERROR ON DDS DECLARATION 

Routing code: 3 

Message issued by segment: DPPSINIT 

Explanation: One of the DDSNAMES cards has been incorrectly coded 
(within the DDSCTLIN stream) . 

Response: Correct the bad DDSNAMES card and resubmit the job. 

DPP056I DDSNAME = XXXXXXXX, PRIMARY = YYYYYYYY, BACKUP = ZZZZZZZZ 

(= OUT-OF-SERVICE) 

Routing code: 3 

Message issued by segment: DPPSMSGI 

Explanation: This message only gives the status of a specified DDS. 

Response: None. 
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DPP057I DDSNAME = XXXXXXXX IS LOCKED OUT 

Routing code: 3 

Message issued by segment: DPPSLOCK 

Explanation: A DDS LOCK is being placed on the DDS in question. 
Response: None. 

DPP058I DDSNAME = XXXXXXXX IS UNLOCKED 

Routing code: 3 

Message issued by segment: DPPSUNLK 

Explanation: A DDS lock is being taken off the DDS in question. 
Response: None. 

DPP059I UNABLE TO CREATE BACKUP FOR DDSNAME = XXXXXXXX 

Routing code: 3 

Message issued by segment: DPPSCRBK 

Explanation: An attempt to create a backup copy is unsuccessful 
because of I/O errors. 

Response: None. 

DPP060I time date (up to 80 characters of user data) 

Routing code: 2 

Message issued by segment: DPPXKILL 

Explanation: The Special Real Time Operating System cancel routine 
displays any operator comments, passed to the cancel 
routine, about the nature of the termination. 

Response: None. 

DPP061I PTIME for TASK X EP Y TERMINATED BY PATCH RC Z 

Routing code: 2 

Message issued by segment: DPPCPTIM 

Explanation: A PATCH was issued by a time service routine in response 
to a previous PTIME request to task X and EP Y, but 
received an error return code of Z from the PATCH 
routine. Therefore, its PTIME for this task and EP have 
been deleted. The return code is output as a hexadecimal 
value. 

Response: None. 

DPP062I DDS REQUEST REJECTED 
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Routing code: 3 

Message issued by segment: DPPSMSGI 

Explanation: A switch was attempted while the backup was out of 
service. 

Response: None. 

DPP063I DDSNAME = XXXXXXXX WAS NOT DECLARED DURING INITIALIZATION 

Routing code: 3 

Message issued by segment: DPPSMSGI 

Explanation: This message follows DPP062I stating that the DDSNAME 
specified is a user command that could not be found 
among the ones declared as duplicates at iniatization 
time. 

Response: None. 

DPP064I DDSNAME = XXXXXXXX, BACKOP IS ALREADY IN SERVICE 

Routing code: 3 

Message issued by segment: DPPSCP.BK 

Explanation: The backup is already in service, so a user request to 
create a backup will not be executed. 

Response: None. 

DPP065I DDSNAME = XXXXXXXX = S CURRENTLY OPENED BY ANOTHER TASK 

Routing code: 3 

Message issued by segment: DPPSMSGI 

Explanation: The user's request for 'REPLACE' cannot be satisfied 
because the DDS is already open. 

Response: None. 

DPP066I time date 

Routing code: 1 

Message issued by segment: DPP2SAMP DPPSAMP1 

Explanation: Test message issued by the Special Real Time Operating 
System sample program. 

Response: None. 

DPP067I ABEND sssuuu AT LOCATION xxxxxx DURING THE SPECIAL REAL 

TIME OPERATING SYSTEM SERVICE OF PL/I - FORT MACRO ID 

yy 
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Routing code: 3 

Message issued by segment: DPPPIF 

Explanation: The message is intended to inform the high level language 
user that a Special Real Time Operating System service 
routine ABENDed with a completion code of sssuuu where 
sss is the system completion code and uuu is the user 
completion code at location xxxxxx for service call 
identified by MACRO ID yy. 

Response: None. 

DPP068I time date #8C1# MACRO FONCTIONING 

Routing code: 1 

Message issued by segment: DPPZSAMP 

Explanation: Test message issued by the Special Real Time Operation 

System sample program. When the sample program executes 
a macro, and the macro executed properly, message DPP068 
will be issued with the macro name. 

Response: None. 

DPP069I time date ITEM DPPSAMP2 CONTENTS ARE #6C1# 

Routing code: 1 

Message issued by segment: DPPZSAMP 

Explanation: Test message issued by the Special Real Time Operating 

System sample program. A GETITEM macro will be executed 
by the sample program. The contents of item DPPSAMP2 
(in array DPPZSAMP) will be displayed via message DPP069. 

Response: None. 

DPP070I time (content of the IMP command which was received) 

Routing code: 1 

Message issued by segment: DPPXIMPP 

Explanation: Contains the IMP command issued by the operator. 

Response: None. 

DPP071I DDS REQUEST REJECTED - REQUEST NOT UNDERSTOOD 

Routing code: 3 

Message issued by segment: DPPSMSGI 

Explanation: A DDS request was entered with a bad format, and the 
DSS input handler could not interpret it. 

Response: None. 
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DPP072I 

Eouting code: 
Message issued 
Explanation : 

Response: 

DPP073I 

Routing code: 
Message issued 
Explanation : 

Response : 

DPP074I 

Routing code: 
Message issued 
Explanation : 

Response : 

DPP075I 
Routing code: 
Message issued 
Explanation: 
Response: 

DPP076I 
Routing code: 
Message issued 
Explanation : 



time date PROGRAM #8C1# PATCHED AS A RESULT OF AN IMP 
COMMAND APPEARS TO BE IN A LOOP 



by segment: DPPXIMPP 

An IMP command vas issued to the SLAVE partition and 
the routine that processes (routine patched by IMP as 
a result of this command) the command appears to be in 
a loop. 

The loop in the processing routine for this particular 
IMP command should be corrected. The loop vill not 
affect the operation of the Special Real Time Operating 
System. 



DDSNAME = XXXXXXXX, UNABLE TO ACCESS DATA SETS COMPARE 
REJECTED 

3 

by segment: DPPSCMPR 

A DDS compare reguest is being rejected because the 
JFCBs for the data sets cannot be read. 

None . 

DDSNAME = XXXXXXXX, DATA SETS NOT SAME TYPE COMPARE 
REJECTED 

3 

by segment: DPPSCMPR 

A DDS compare request was made for data sets with 
different DSORG fields in the DSCBS, so the request is 
being dropped. 

None. 

DDSNAME = XXXXXXXX, COMPARE IN PROGRESS 
3 

by segment: DPPSCMPR 

The DDS specified is now being compared. 

None. 



DDSNAME = XXXXXXXX, COMPARE ENDED DATA SETS ARE EQUAL 

3 

by segment: DPPSCMPR 

A DDS compare function ended, and the two data sets were 
found to be equal. 
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Response: 



None . 



DPP077I 

Routing code: 
Message issued 
Explanation : 

Response: 

DPP078I 

Routing code: 
Message issued 
Explanation : 

Response: 

DPP079I 

Routing code: 
Message issued 
Explanation: 
Response: 

DPP080A 
Routing code: 
Message issued 
Explanation: 

Response: 

DPP081 A 
Routing code: 
Message issued 
Explanation : 



DDSNAME = XXXXXXXX, COMPARE ENDED, DATA SETS ARE NOT 
EQUAL 

3 

by segment: DPPSCMPR 

A DDS compare function ended with the data sets not 
being equal; lEBCOMPR output is on the COMPRINT report 
data sets. 

None. 



DDSNAME = XXXXXXXX, COMPARE REJECTED, NO //DDSCMPIN DD 
CARD FOR SYSIN 

3 

by segment: DPPSCMPR 

A DDS compare request is being dropped because there is 
no DDSCMPIN DD card in the II07 to hold lEB COMPR input. 

None 



time IMP PARAMETERS EXCEED MAXIMUM PARAMETERS DEFINED 
FOR IMP COMMAND cccccccc 

1 

by segment: DPPXIMPP 

Too many parameters were passed by the IMP command. 

The IMP command should be issued again, not exceeding 
the maximum number of parameters for this particular 
IMP command. 

FAIL/RST DATA SET NOT WRITTEN - END OF EXTENT ON DPPFAIL 

5 

by segment: D0MIRFL2 

The data set named in the DPPFAIL DD card contains 
insufficient space for the failure/restart data set. 

Allocate more space. 

FAIL/RST DATA SET NOT WRITTEN - I/O ERROR ON DPPFAIL 
5 

by segment: D0MIRFL2 

An I/O error occurred on the Failure/Restart data set. 
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Response: Use a different disk or allocate the space at a different 

place on the disk pack. Hardviare error. 

DPP082A FAIL/RST DATA SET NOT WRITTEN - I/O ERROR READING PAGING 

DATA SET 

Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: An I/O error reading the 0S/VS1 paging data set. 
Response: An IPL will be required. Hardvare error. 

DPP083A FAIL/RST DATA SET WRITTEN - I/O READING JOBQOEOE/S YSWADS 

Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: An I/O error occurred while reading the 0S/VS1 Job queue 
or SYS1.SYSWADS data sets. 

Response: An IPL will be required. Hardware error. 

DPP084A FAIL/RST DATA SET NOT WRITTEN - I/O ERROR READING SWADS 

Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: An I/O error occurred while reading the SWADS for the 
MASTER partition. 

Response: Hardware error, A different SWADS will probably be 

required. 

DPP085A FAIL/RST DATA SET NOT WRITTEN - I/O READING SWADS FOR 

SLAVEPART 

Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: An I/O error occurred while reading the SWADS for the 
SLAVE partition. 

Response: Hardware error. A different SWADS will probably be 

required. 

DPP086A FAIL/BST DATA SET NOT WRITTEN - PROG CK. IN RESTART 

WRITE 

Routing code: 5 

Message issued by segment: D0HIRFL2 

Explanation: An unexplained program check occurred in restart write. 
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Response: Probable programming error in Failure/Restart. 

DPP087A FAIL/RST DATA SET NOT WRITTEN - MACHINE CHECK IN RESTART 

Routing code: 5 

Mfcssage issued by segment: D0MIRFL2 

Explanation: A hardware error occurred in restart write. 
Response: Retry the job. 

DPP088A SECNDRY COPY OF FAIL/RST DATA SET NOT WRITTEN I/O ERROR 

ddname 

Routing code: 5 

Message issued by segment: DOMIRCPY 

Explanation: An I/O error occurred while attempting to make backup 

copies of the failure/ re start data set. No backup copies 
were made. Insufficient space in the data set can cause 
this error- 
Response: Possible hardware error. Allocate the backup 

failure/restart data set at a different location or 
increase its size. 

DPP089A DDNAME ddname INVALID FOR COPY OF F/R DATA SET 

Routing code: 5 

Message issued by segment: DOMIRCPY 

Explanation: The ddname indicated is invalid for the failure/restart 
data set for one or more of the following reasons: 

• It is not a direct access device of the same type as the primary 
F/R data set. 

• Another F/R data set is on the volume. 

• The volume contains the SYS1. NUCLEUS data set. No backup copies 
were made. 

Response: Correct the JCL. 

DPP090I FAIL/RST DATA SET WRITTEN 

Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: The Failure/Restart data set has been successfully 
written. 

Response: None. 

DPP091I FAIL/RST DATA SET READ COMPLETE 
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Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: The Failure/Restart data set had been successfully iPLed. 
Response: None. 

DPP092A FAIL/RST DATA SET NOT WRITTEN - DPPFAIL DD CARD INVALID 

OR MISSING 

Routing code: 5 

Message issued by segment: D0MIRFL2 

Explanation: The Failure/Restart data set was not written because of 
one or more of the following: 

• No DPPFAIL DD card is provided. 

• The data set name in the DPPFAIL DD card is not on direct access. 

• The data set named in the DPPFAIL DD card is on the same volume 
with SYS1 .NUCLEUS. 

Response: Correct the JCL and resume the job. 

DPP093I FAIL/RST DATA SET NOT WRITTEN - OTHER R/T JOB IN SYSTEM 

Routing code: 5 

Message issued by segment - D0MIRFL2 

Explanation: Another realtime job in the same 0S/VS1 system owns 
restart write eligibility. 

Response: None. 

DPP094A PROBE FUNCTION NOT RUNNING IN OTHER CPU 

Routing code: 5 

Message issued by segment: DOMIRCMN 

Explanation: This message can appear only in systems with CMCKPRB=YES 
specified in the FAILRST SYSGEN macro. It indicates 
that neither a continuous monitor or a PROBE is running 
in the backup CPU. 

Response: Start a PROBE function in the backup CPU if desired. 

DPP095I PROBE FUNCTION IS NOW RUNNING IN OTHER CPU 

Routing code: 5 

Message issued by segment: DOMIRCMN 

Explanation: Thi^ message can appear only in systems with CMCKPRB=YES 
specified in the FAILRST SYSTEN macro. It indicates 
that the continuous monitor has detected that a PROBE 
function is running in the other CPU. 
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Response: 



None. 



DPP096I ANOTHER CONT. MON IS IN OTHER CPO 

Routing code: 5 

Message issued by segment: DOMIRCMN 

Explanation: This message can appear only in systems with CMCKPRB=YES 
specified in the FAILRST SYSGEN macros. It indicates 
that each CPU has a continuous monitor running in duplex 
mode. Each CPO is operating as though it were the prime 
CPU. 

Response: Cancel the realtime job in one of the CPUs unless the 

configuration is specified. 

DPP098A CONTINUOUS MONITOR RECOMMENDS FAILOVER 

Routing code: 5 

Message issued by segment: DOMIRCMN 

Explanation: The continuous monitor has detected an error in the 

online system and is recommending a failure or restart. 

Response: Allow the failover to occur or invoke a restart as 

appropriate. 

DPP099I ANOTHER CONT. MON/PROBE ON SAME SYSTEM - NO HARDWARE 

FAILOVER RECOM BY THIS CONT. MON 

Routing code: 5 

Message issued by segment: DOMIRCMN 

Explanation: One of the following conditions exists: 

• This realtime job does not own restart write eligibility. 

• A PROBE function is running in another job on this CPU. 

• A continuous monitor is already running in duplex mode on this CPU. 
Response: None. 

DPP800I CONTROL STATEMENT LABEL MUST NOT EXCEED EIGHT CHARACTERS 

Routing code: SYSPRINT 

Message issued by segment: DPPINITO 

Explanation: The LABEL field of a control statement had a name that 
exceeded eight characters. Eight is the maximum 
allowable number of characters in this field. 

Response: Correct the name in the LABEL field and resubmit. 

DPP801I CONTROL STATEMENT MUST HAVE OPERANDS 
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Routing code: SYSPPINT 

Message issued by segment: DPPINITO,DPINITOA 

Explanation: All control statements except ABEND must ha¥e OPERANDS 
that begin on the same card as the OPERATION. 

Response: Supply the proper OPERANDS and resubmit. 

DPP802I INVALID OPERATION FIELD 

Routing code: SYSPRINT 

Message issued by segment: DPPINITO 

Explanation: An OPERAND other than one of the following was found: 
PATCH, WAIT, WRITE, TCB, GETWA, CBGET, ABEND, MASTER, 
SLAVE, DBREF. 

Response: Correct the OPERATION field and resubmit. 

DPP803I TOO MANY OPERANDS ON CONTROL STATEMENT 

Routing code: SYSPRINT 

Message issued by segment: DPINIT03 

Explanation: The maximum number of OPERAND characters allowed on any 
one control statement and its continuations is 255 
characters. 

Response: Correct the control statement and resubmit. 

DPP80UI INVALID CONTROL STATEMENT CONTINUATION 

Routing code: SYSPRINT 

Message issued by segment: DPINIT03 

Explanation: A continuation was indicated and the card processed 

either began in column 15 or before, or processing was 
not within guotes and the continuation did not start in 
column 16. 

Response: Correct the control statement a.nC\ retry. 

DPP805I INVALID OPERAND ON CONTROL STATEMENT 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 ,DPI NITOA 

Explanation: The control statement contains an invalid operand for 
the operation type specified in the operation field. 

Response: Correct the control statement and retry, 

DPP806I ONLY ONE MASTER OP SLAVE STATEMENT ALLOWED IN INPUT 

STREAM 
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Routing code: SYSPRINT 

Message issued by segment: DPPINITO 

Explanation: Only one MASTER or SLAVE control statement is allowed 

in each SYSINIT input stream. 

Response: Remove the extra MASTER or SLAVE statement (s) from the 

stream and retry- 

DPP807I NAME SPECIFIED ON WAIT STATEMENT NOT A LABEL ON A 

PREVIOUS PATCH CONTROL STATEMENT 

Routing code: SYSPRINT 

Message issued by segment: DPINITOt 

Explanation: The operand on the WAIT statement nas not a label from 
a PATCH statement which precedes the WAIT in the input 
stream. 

Response: Correct the WAIT operand, remove the WAIT, or place the 

proper PATCH statement ahead of the WAIT in the input 
stream and retry. 

DPP808I ONLY ONE RESTART STATEMENT ALLOWED IN THE INPUT STREAM 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: The input stream contained more than one WRITE RESTART 
statement. Only one is valid. 

Response: Remove the extra WRITE RESTART statement (s) from the 

SYSINIT stream and retry. 

DPP809I INVALID NAME IN EP=FIELD 

Routing code: SYSPRINT 

Message issued by segment: DPINIT02 

Explanation: The name specified on an EP= keyword of a PATCH statement 
exceeded eight characters. 

Response: correct the EP- operand and retry. 

DPP810I INVALID NAME IN TASK= FIELD 

Routing code: SYSPRINT 

Message issued by segment: DPINIT02 

Explanation: The TASK* keyword of a PATCH statement contained a task 
name which exceeded eight characters. 

Response: Correct the TASK= operand and retry. 
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DPP811I QL FIELD INVALID 

Routing code: SYSPRINT 

Message issued by segment: DPIMIT02 ,DPPINITOA 

Explanation: The QL= keynord on a PATCH statement contained a value 
of greater than 99 9. 

Response: Correct the QL= keyword operand and retry. 

DPP812I ID FIELD INVALID 

Routing code: SYSPRINT 

Message issued by segment: DPINIT02 

Explanation: The ID= keyword on a PATCH statement contained an ID 
greater than 255. 

Response: Correct the ID= keyword operand and retry. 

DPP813I INVALID KEYWORD 

Routing code: SYSPRINT 

Message issued by segment: DP PI NI TO, DPI NI TO A 

Explanation: The control statement contained an invalid keyword for 
the operation type specified in the operation field. 

Response: Correct the keyword and retry. 

DPPSiai PRTY REFERENCE VALUE MISSING OR INVALID 

Routing code: SYSPRINT 

Message issued by segment: DPINIT02 ,DPI NITO A 

Explanation: The PRTY= keyword on the PATCH statement was either 

missing the reference value or the value exceeded 255. 

Response: Correct the PRTY reference value and retry. 

DPP815I INVALID DELIHETER IN PRTY OPERAND 

Routing code: SYSPRINT 

Message issued by segment: DPINIT02 

Explanation: The PRTY= keyword on a PATCH statement was not coded as 
JOBSTEP - or (jobname, ). The delimiter must be the 
minus {-) or the comma (,) . 

Response: Correct the PRTY= keyword operand and ensure that if 

(jobname,) is used that the specified jobname does not 
exceed eight characters. 

DPP816I INVALID TASK NAME IN PRTY REFERENCE FIELD 
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Routing code: SYSPRINT 

Message issued by segment: DPINIT02 

Explanation: The PRTY= keyword on the PATCH statement contained a 
name in the (jobname,) field which exceeded eight 
characters - 

Response: Correct the PRTY reference jobname and resubmit. 

DPP817I DOPLICATE KEYWORD ON PATCH STATEMENT 

Routing code: SYSPRINT 

Message issued by segment: DPINIT02 

Explanation: A keyword operand on the PATCH statement appeared twice 
on a single control statement. 

Response: Correct the control statement and retry, 

DPP818I INVALID DELIMETER IN PARAM SOBOPERANDS 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01 

Explanation: All suboperands within a PARAM field must end with a 

single guote (•) character and be delimited by a comma. 
This PATCH statement contained a suboperand that was 
not delimited with a comma. 

Response: Correct the control statement and retry. 

DPP819I INVALID DATA IN PARAM FIELD 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01 

Explanation: The PARAM= keyword operand on a PATCH statement contained 
non-decimal data in an F' ' field, or non-hexadecimal 
data in an X' ' field. 

Response: Correct the PARAM data and retry. 

DPP820I INVALID DATA TYPE IDENTIFIER IN PARAM FIELD - MUST BE 

X, F, OR C. 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01. 

Explanation: The PARAM= keyword on a PATCH statement contains a data 
type identifier other than F, or C. 

Response: Correct the data type identifier and retry. 

DPP821I CHARACTER FOLLOWING PARAM DATA TYPE IDENTIFIER MUST BE 

A QUOTE 



OPERATOR'S REFERENCE a-U7 



Routing code: 



SYSPRINT 



Message issued by segment: DPINIT01 

Explanation: The data type identifier (F, C, or X) on a PATCH 
statement must be followed by a single quote (•) 
character. 

Response: Correct the PARAM field and retry, 

DPP822I UNBALANCED QUOTES IN PARAM FIELD 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01 

Explanation: A PARAM keyword on a PATCH statement must contain evenly 
balanced single quote (') characters. This character 
is not valid with a PARAM suboperand. 

Response: Correct the PARAM statement and retry. 



DPP823I PARAM FIELD MOST END WITH RIGHT PARENTHESIS 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01 

Explanation: The PARAM= keyword suboperands on a PATCH statement must 
be enclosed in parentheses ( — ) ; the ending or right 
parenthesis is missing on this PATCH statement. 

Operator response: Correct the PARAM field and retry. 



DPP821II PARAM FIELD MUST START WITH LEFT PARENTHESIS 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01 

Explanation: The PARAM= keyword suboperands on a PATCH control 

statement must be enclosed in parentheses ( — ) ; the 
beginning or left parenthesis on this PATCH statement 
is missing. 

Response: Correct the PARAM field and retry. 



DPP825I INVALID DELIMETER FOLLOWING PARAM OPERAND 

Routing code: SYSPRINT 

Message issued by segment: DPINIT01 

Explanation: All operands on a PATCH statement must be delimited with 
a comma or blank. This control statement has a character 
other than a comma or blank following the ending (right) 
parenthesis. 

Response: Correct the statement and retry. 
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DPP826I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP827I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP828I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP829I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP830I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP831I 
Routing code: 



QL FIELD CONTAINS NONDECIMAL DATA 
SYSPRINT 

by segment: DPINIT02 

The QL= operand on the PATCH statement contained a value 
that included non-decimal characters. 

Correct the QL= operand and retry. 



ID FIELD CONTAINS NONDECIMAL DATA 
SYSPRINT 

by segment: DPINIT02 

The ID= keyword on the PATCH statement contained a value 
that included no n- decimal data. 

Correct the ID field and retry. 



PRTY FIELD CONTAINS NONDECIMAL DATA 
SYSPRINT 

by segment: DP INIT02 ,DPI NITOA 

The PRTY = keyword on the PATCH statement contained a 
priority reference value that included a non-decimal 
character (s) . 

Correct the PRTY reference value and retry. 



CBGET DATA IS NONDECIMAL 
SYSPRINT 

by segment: DPINITOU 

The CBGET statement operand contained a value which 
included a non-decimal character (s) . 

Correct the CBGET operand and retry. 



INVALID JOBNAME 
SYSPRINT 

by segment: DPINITOU 

A MASTER or SLAVE statement had an invalid jobname on 
its operand- The jobname exceeds eight characters. 

Correct the MASTER or SLAVE statement jobname and retry. 



TIME FIELD CONTAINS NONDECIMAL DATA 
SYSPRINT 
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Message issued by segment: DPINITOU 

Explanation: The time field on the ABEND card contained a value that 
included a non-decimal character (s) . 

Response: Correct the time field on the CBGET statement and retry, 

DPP832I TIME FIELD CANNOT BE GREATER THAN 999 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: The time field on the ABEND card contained a value 
greater than 999- 

Response: Correct the time field and retry. 

DPP833I SECOND OPERAND ON AN ABEND STATEMENT MUST BE DUMP OR 

OMITTED 

Routing code: SYSPRINT 

Message issued by segment: DPINITOt* 

Explanation: The second operand on the ABEND statement contained 
characters other than the word 'DUMP*. This operand 
must be 'DUMP* or omitted. 

Operator response: Correct the ABEND statement and retry. 

DPP83UI NUMBER OF TCBS IS NONDECIMAL 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: The operand on the TCB statement contained a value that 
included a non-decimal character (s) . 

Response: correct the TCB statement and retry. 

DPP835I EP= MUST BE SPECIFIED ON A PATCH STATEMENT 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: The PATCH statement processed did not have the EP« 
keyword specified. 

Response: Correct the EP= and retry. 

DPP836I INPUT DCB - SYSINIT - FAILED TO OPEN 

Routing code: SYSPRINT 

Message issued by segment: DPPINITO 
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Explanation : 
Response: 

DPP837I 
Routing code: 
Message issued 
Explana tion : 

Response: 

DPP838I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP839I 
Routing code: 
Message issued 
Explanation : 

Response: 

DPP8U0I 

Routing code: 
Message issued 
Explanation : 

Response: 

DPP8U1I 

Routing code: 
Message issued 
Explanation : 



The input DCB for the SYSINIT data set could not be 
opened. 

Check the SYSINIT DD card and verify that it allocates 
the correct data set. 



INVALID SUBPARAMETERS IN LIST 
SYSPRINT 

by segment: DPINIT04 

The GETWA statement contained subparameters in its size 
list which were invalid or had invalid delimiters. 

Correct the GETWA statement and retry. 



LIST ENTRY CONTAINS NONDECIMAL DATA 
SYSPRINT 

by segment: DPINITOU 

The GETWA suboperand list contained subparameters that 
contained a non-decimal character (s) - 

Correct the GETWA statement and retry. 



NUMBER OF BLOCKS CANNOT EXCEED 4095 
SYSPRINT 

by segment: DPINIT04 

The GETWA statement had a request for a number of blocks 
and the request exceeded the maximum of 4095. 

Correct the GETWA statement and retry. 



GETWA SIZE EXCEEDS 30720 OR GREATER THAN 2048 AND NOT 
A 2K MULTIPLE OR NOT A MULTIPLE OF 8 

SYSPRINT 

by segment: DP IN IT 04 

The GETWA statement contained a request for a block size 
that exceeded the maximum size or is an invalid size. 

Correct the GETWA statement and continue. 



EXCESSIVE NUMBER OF SUBOPERANDS IN LIST -64 IS THE 
MAXIMUM 

SYSPRINT 

by segment: DPINIT04 

The GETWA statement contained a list of subparameters 
with more than 64 subparameters. 
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Response: 



Correct the GETWA statement and retry. 



DPP8a2I SOBLIST MOST END WITH RIGHT PARENTHESIS 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: the GETWA statement contained a list of subparameters 
that did not end with a right parenthesis. 

Response: Correct the GETWA statement and retry. 

DPP843I SOBLIST MOST BEGIN WITH A LEFT PARENTHESIS 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: The GETWA statement contained a subparameter list that 
did not begin with a left parenthesis. 

Response: Correct the GETWA statement and retry. 

DPPSaUI CONTINOATION EXPECTED - NOT RECEIVED 

Routing code: SYSPRINT 

Message issued by segment: DPINIT05 

Explanation: The last statement read from the input stream indicated 
that a continuation statement was to follow. The 
continuation statement was not in the input stream. 

Response: Correct the last statement or add the continuation 

statement and retry. 

DPPSaSI TWO-PARTITION FUNCTION NOT AVAILABLE 

Routing code: SYSPRINT 

Message issued by segment: DPINIT04 

Explanation: The input stream contains a MASTER or SLAVE statement; 

however^ at SRTOS SYSGEN, two- partition operation was 
not selected. 

Response: Remove the MASTER or SLAVE statement and retry. 

DPP8U6I nnnnnnnn DEFINED AS QUEUE HOLDER BUT NOT REFERENCED BY 

ANY QOEUE PROCESSOR 

Routing code: SYSPRINT 

Message issued by segment: DPINIT05 

Explanation: A QH statement defined nnnnnnnn as a gueue holder but 
that name is not specified on any QP statement. If 
allowed to go into execution, work that is queued to 
this queue holder could never be executed. 
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Response: 



Remove the QH card that specified this name or add this 
name to some QP statement and retry. 



DPP847I nnnnnnnn REFERENCED aS QUEUE HOLDER BY A QUEUE PROCESSOR 

BUT NOT DEFINED 

Routine Code: SYSPRINT 

Message issued by segment: DPINIT05 

Explanation: The name nnnnnnnn appears in the QH= operand of a QP 

statement but is not defined as a queue holder by a QH 
statement. 

Response: Define a queue holder by this name or delete this name 

from the QP statement that references it and retry. 



Dppeaei (qh name) 

Routing code: SYSPRINT 

Message issued by segment: DPINITOA 

Explanation: A QH name or QP number is required on every QH or QP 

statement as a positional parameter. This parameter is 
missing or invalid on the user statement preceding this 
message. 

Response: Correct the statement and retry. 



DPP8a9I cccccccc OPERAND CONTAINS TOO MANY, TOO FEW OR ILLEGAL 

CHARACTERS IN PARAMETER OR SUB-PARAMETER 

Routing code: SYSPRINT 

Message issued by segment: DPINITOA 

Expalanat ion: The operand specified by cccccccc is invalid on the user 
statement preceding this message. 

Response: Correct the statement and retry. 



DPP850A SxxIN TASK JYYYYYYY- ABEND #nnn FOR MODULE zzzzzzzz- 

REPLY 'YES' TO ALLOW DUMP OR 'NO' TO SUPPRESS DUMP. 

Routing code: The message is issued as an 0S/VS1 WTOR 

Message issued by segment: DPPSTAE 

Explanation: A subtask ABENDed while the "STAE- OPTION" request «as 
in effect. The operator may reply 'YES' to allow the 
dump to be formatted or 'NO' to suppress the dump. If 
the operator has not replied to this WTOR in 5 minutes, 
the WTOR will be cancelled and the dump formatting will 
be bypassed. The message defines the type of ABEND and 
the module responsible, where: 

XXX - is the ABEND code 

YYYYYYYY - is the task name 
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nnn - is the total number of ABENDS for this module 



ZZZZZZZZ - is the entry point name of the module 

Messages DPP860 and DPP861 are issued in conjunction 
with this WTOR to provide the PSW and register contents 
at the time of the ABEND. 

Response: Reply 'YES» to allov the dump to be formatted. 

Reply 'NO' to suppress formatting of the dump. 



DPP851I {YES} 

(NO } DOMP REPLY ACCEPTED 

REPLY NOT RECEIVED IN TIME INTERVAL. DUMP BYPASSED 
XXX IS AN INVALID REPLY 

Routing code: The message is issued as an 0S/VS1 WTO 

Message issued by segment: DPPTSTAE 

Explanation: This message is issued in response to the operator reply 
to WTOR DPP850A. 'DPP851I 'YES' DUMP REPLY ACCEPTED' 
indicates that the operator reply was valid and issued 
within the time interval and a dump will be formatted. 
'DPP85 1I »N0' DUMP REPLY ACCEPTED' indicates that the 
operator reply was valid and issued within the time 
interval and dump formatting will be bypassed. 'DPP851I 
REPLY NOT RECEIVED IN TIME INTERVAL- DUMP BYPASSED' 
indicates that no operator reply was received within 
the time interval and dump formatting will be bypassed. 
'DPP851I XXX IS AN INVALID REPLY' states that the 
operator reply was not a 'YES' or 'NO' and the WTOR 
DPP850A will be reissued- 

Response: None. 



DPP852I 


cccccccc 0 


PERAND CONTAINS INVALID 


DATA 


Routing code: 


SYSPRINT 






Message issued 


by segment 


: DPINITOA 




Explanation : 


The operan 
preceding 


d specified by cccccccc 
this message contains in 


on the user 
valid data. 


Response: 


Correct th 


e statement and retry. 





DPP853I cccccccc OPERAND DATA MUST BE ENCLOSED IN PARENTHESIS. 

ONE OB BOTH ARE MISSING 

Routing code: SYSPRINT 

Message issued by segment: DPINITOA 

Explanation: The operand data of the parameter specified by cccccccc 
must be enclosed in parenthesis. Either the opening or 
closing parenthesis or both are missing on the user 
statement preceding this message. 

Response: Correct the statement and retry. 
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DPP85ai 



cccccccc 



Routing code: SYSPRINT 

Message issued by segment: DPINITOA 

Explanation: The operand specified by cccccccc is required, but not 
correctly provided on the user statement preceding this 
message. Other messages may appear in conjunction with 
this message. 

Response: Correct the statement and retry. 



DPP855I cccccccc SPECIFIED AS EXIT= OPERAND NOT FOOND ON 

STEPLIB/JOBLIB DATA SET 

Routing code: SYSPRINT 

Message issued by segment: DPINITOA 

Explanation: A STAEX command specifies cccccccc as an exit routine 
load module. The initialization routine has executed 
a BLDL and found that the load module could not be 
fetched if it should be needed. 

Response: Add a load module by the specified name to the 

STEPLIB/JOBLIB data set(s) and retry. 



DPP856I {QP NUMBER) 

{QH NAME } SPECIFIED ON THIS STATEMENT HAS BEEN 
SPECIFIED ON A PREVIOUS STATEMENT 

Routing code: SYSPRINT 

Message issued by segment: DPINITOA 

Explanation: The queue processor number or queue holder name specified 
as a positional parameter on the user statement preceding 
this message has been defined on a previous QP or QH 
statement- 
Response: Remove the duplicate specifications and retry. 



DPP857I cccccccc IS CONNECTED TO MORE THAN 21 OTHER BLOCKS 

Routine code: SYSPRINT 

Message issued by segment: DPINITOA 

Explanation: the QH= operand of a QP statement is not allowed to 
contain more than 21 queue holder names and a queue 
holder name is not allowed to appear in more than 21 QP 
statement QP= operands, cccccccc is the QH or QP name 
that violates this restriction, A QP name is in the 
format ****QPnn, vhere nn is the user defined queue 
processor number. 

Response: Reduce the number of references to the specified name 

and retry. 
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DPP860 



PSW AT ABEND xxxx xxxx 



Routing code: 1 

Message issued by segment: DPPTSTAE 

Explanation: Whenever an OS dump is suppressed by the STAE option 
processing (i.e., "STAE, NODUMP") or whenever 
"STAE, OPTION" is in effect, messages DPP860 and DPP861 
are issued to provide a mini dump. Message DPP860 
provides the PSW at the time of the ABEND. 

Response: None. 



DPP861 REGS aaaa bbbb cccc dddd 

Routine code: 1 

Message issued by segment: DPPTSTAE 

Explanation: whenever an OS dump is suppressed by the STAE option 
processing (i.e., "STAE, NODUMP") or whenever 
"STAE, OPTION" is in effect, messages DPP860 and DPP861 
are issued to provide a mini dump. Message DPP861 is 
issued four times to provide the contents of registers 
0-3, 4-7, 8-11, and 12-15, respectively at the time of 
the dump. 

Response: None. 



(QP} {PATCH} 
DPP862I QQQQQQQQ: IS {QH} {NOPATCH} 

(T SK} 

{HOLD} {SEQ} 

{REL} , {NONSEQ} ,CQL = nnn,[ A] 



Routine code: 2 



Message issued by segment: DPPTQIMP 

Explanation: This message is output as a result of the entry of every 
QS command. It reports the status of the gueue 
processor (s) , queue holder (s) , and/or independent tasJc(s) 
specified in the QS command. 

QQQQQQQQ is the name of the unit being reported 



QP - This is a queue processor 

QH - This is a queue holder 

TSK - This is an independent task 

PATCH - This unit is allowed to accept work (PATCHes) 

NOPATCH - PATCHes to this unit will be rejected 

HOLD - This unit is not allowed to start processing 
any new work 

REL - This unit can process any work which it is 

eligible to process 
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SEQ - (meaningful for QH only) only one QP may be 

processing work from this QH 

NONSEQ - (meaningful for QH only) any QP connected 
to this QH may take work from this QH 

CQL=nnn - nnn is the number of work queues currently 
awaiting processing 

A - If present, this unit (TSK or QP only) is 

currently processing a piece of work 

Response: None. 



{QH} 

DPP863I QQQQQQQQ IS (QP) XREF TO: 

nnnnnnnn,. . . r nnn nnn 

Routing code: 2 

Message issued by segment: DPPTQIMP 

Explanation: This message is output as a result of the entry of a QS 
command with the SREF operand. It is output following 
message DPP962. QQQQQQQQ is the unit being reported. 
QP or QH specifies the type of unit, queue processor or 
queue holder. If QP, the names following (nnnnnnnn, . . . ) 
are the queue holders from which this QP may select 
work. If QH, the names following are the queue 
processors that may select work from this QH. Up to 7 
names of connected units may appear in each message. 
Op to 3 messages may be output to output all connections 
to one unit. 

Response: None. 

DPP864I QS COMMAND PARAMETER PPPPPPPP INVALID. COMMAND IGNORED 

Routing code: 2 

Message issued by segment: DPPTQIMP 

Explanation4 A QS IMP command was entered with a misspelled, out of 
sequence or invalid parameter. The unacceptable 
parameter is reproduced as PPPPPPPP. 

Response: Reenter request with correct parameters. 

DPP865 COPY FAILED FOR 'FROM-00' TO 'TO-00' 

Routing code: 3 

Message issued by segment: DPPSRTCP 

Explanation: The realtime copy operation pursuant to an RTCOPY command 
has failed. 

Response: None. 

DPP866 UNABLE TO READ OFCBS FOR '00 NAME' 
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Routine code: 3 

Message issued by segment: DPPSRTCP 

Explanation: In a realtime copy operation, the JFCB for the DDname 
could not be read. 

Response: None. 

DPP867 UNABLE TO READ COUNT FOR 'DDNAME' 

Routing code: 3 

Message issued by segment: DPPSRTCP 

Explanation: In a realtime copy operation the count fields for ddname 
could not be read. 

Response: None, 

DPP868 UNABLE TO READ RO FOR ddname 

Routine code: 3 

Message issued by segment: DPPSRTCP 

Explanation: In a realtime copy operation, RO could not be read for 
ddname . 

Response: None. 

DPP869 UNABLE TO READ DATA FOR ddname 

Routing code: 3 

Message issued by segment: DPPSRTCP 

Explanation; In a ^ealtime copy operation, the data fields could not 
be read for ddname. 

Response: None. 

DPP870 UNABLE TO WRITE DATA FOR DDNAME 

Routine code: 3 

Message issued by segment: DPPSRTCP 

Explanation: In a copy operation, the data could not be written for 
ddname , 

Response: None. 

DPP871 COPY ENDED FOR 'ddname--l» TO •ddname-2» 

Routing code: 3 

Message issued by segment: DPPSRTCP 
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Explanation: The realtime copy operation requested by a RTCOPY command 
for ddname-1 to ddname-2 has ended. 

Response: None. 



DPP880 UNABLE TO OPEN DDSTATDS, RUNNING SINGLE MODE 

Routine code: 3 

Message issued by segment: DPPSINIT 

Explanation: When attempting to run REFRESH or READONLY mode, the 
DDSTATUS data set could not be opened. 



Response 



None, 



DPP881 UNABLE TO WRITE DDSTATUS RECORD 

Routine code: 3 

Message issued by segment: DPPSWRST 

Explanation: The status of a DDS changed (or was being initialized) 

but the record could not be written to the DDSTATUS data 
set. 



Response : 



None. 



DPP882 UNABLE TO READ DDSTATU-S RECORD, RUNNING SINGLE MODE 

Routing code: 3 

Message issued by segment: DPPSINIT 

Explanation: When running REFRESH or READONLY, the DDSTATUS data set 
record could not be read. 



Response: 



None. 



DPP883 DDSTATUS NOT OPEN FOR OUTPUT 

Routing code: 3 

Message issued by segment: DPPSWRST 

Explanation: The status of a DDS changed (or was being initialized) 

but the DDSTATUS data set could not be opened for output, 



Response: 



None. 



DPP884 DDSTATUS NOT UPDATED, RUNNING IN READONLY MODE 

Routing code: 3 

Message issued by segment: DPPSWRST 

Explanation: The status of a DDS changed while running in READONLY 
mode, so the DDSTATUS data set will not be updated. 
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Response: 
DPP885 

Eouting code: 
Message issued 
Explanation: 

Response : 

DPP886 

Eouting code: 
Message issued 
Explanation: 

Response: 

DPP887 

Routing code: 
Message issued 
Explanation : 

Response : 

DPP888 

Eouting code: 
Message issued 
Explanation : 

Response : 

DPP889 

Routing code: 
Message issued 
Explanation : 

Response: 



None. 



DDSTATOS HAS BEEN UPDATED 

3 

by segment: DPPSHRST 

The status of a DDS changed or was being initialized 
and the DDSTATOS data set was updated. 

None . 



DDSTATUS RECORD HAS MISSING DDSNAMES - OSING CURRENT 
DECLARATIONS 

3 

by segment: DPPSRSTR 

The DDS declaration for the primary CPU has at least 
one missing declaration from the backup CPU. 

None. 



DDSTATUS RECORD HAS EXTRA DDNAMES, SETTING THEM IN SING 
MODE 

3 

by segment: DPPSRSTR 

The primary CPU had at least one DDS declaration that 
the backup did not have. 

None . 



DDS RESTART IS COMPLETE 

3 

by segment: DPPSRSTR 

The refresh of the DDS status has been completed at 
fail over /restart time. 

None . 



COPY REQUEST REJECTED, RUNNING IN SINGLE MODE 

3 

by segment: DPPSCRBK 

A DDS CREATE was attempted against a data set not 
declared duplicate. 

None. 
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DPP890 UNABLE TO OPEN DD STATUS FOR INPUT RUNNING UITH OLD 

BACKUP CPU DECLARATIONS 

Routing code: 3 

Message issued by segment: DPPSBSTR 

Explanation: At fai lover/re start time, the DD status data set could 
not be opened for input. The DDS declarations of the 
backup CPU were used. 

Response: None. 

DPP891 SYNAD READING DD ST AT US RECORD, RUNNING WITH OLD BACKUP 

CPU DECLARATIONS 

Routing code: 3 

Message issued by segment: DPPSRSTR 

Explanation: At fai lover/re star t time, a synad occurred trying to 
read the DDSTATUS record. The backup CPU DD2 
declarations will be used. 

Response: None. 

DPP892 EOD READING DDSTATUS RECORD, RUNNING WITH OLD BACKUP 

CPU DECLARATIONS 

Routing code: 3 

Message issued by segment: DPPSRTCP 

Explanation: At f ailorer/restart time, the attempt to read the 
DDSTATUS record resulted in End of data. The DDS 
declarations for the backup CPU will be used. 

Response: None. 

DPP893 LOAD MODULE cccccccc NOT FOUND BY PLAYBACK 

Routing code: message is issued as an OS/VS WTO 
Message issued by segment: DPPXDPB 

Explanation: A load module name was passed to playback that could 

not be found in the specified JOBLIB of STEPLIB DD cards 

Response: Resubmit the playback job with a valid load module name 

and/or STEPLIB data set. 

DPP89a INVALID START OR STOP DATA PASSED TO PLAYBACK 

Routing code: message is issued as an OS/VS WTO 
Message issued by segment: DPPXDPB 

Explanation: A start or stop date was passed to playback that could 
not be converted to a valid julian date. 
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Response: Resubmit the playback job with correct dates in the 

following format: 

DD/MMM/YY 

where 

DD is the day of year 

MMM is month of year (only first 3 letters of month 

are specified Jan-Dec) 
YY is year- 

DPP0895 DATA RECORD DISABLED DOE TO UNUSUAL CONDITIONS 

Routing code: 1 

Message issued by segment: DPPXDRC 

Explanation: Data record disabled due to one of the following 
conditions : 

• ABEND in data recording task (DPPXPRINT) 

• I/O errors 

• Data record data set reached end of volume. 

Response: Data record may be restarted (enabled) after it has been 

disabled by the Special Real Time Operating System if 
one of the following conditions are found: 

• The data set is still usable and was allocated with a DISP=OLD or 
NEW. 

• The data set was allocated with DISP=MOD and with space remaining 
on the data set. 

DPP896 NO DATA FOUND BY PLAYBACK WITHIN SPECIFIED TIME AND ID 

RANGE 

Routing code: Message is issued as an OS/VS WTO 
Message issued by segment: DPPXDPB 

Explanation: No data was found by playback within specified time and 
ID range. 

Response: Assure that the time and date are properly specified on 

the playback request and that the data set specified 
does contain data within that time interval. 

DPP897 INCOMPLETE RECORD FOUND BY PLAYBACK 

Routing code: The message is issued as an 0S/VS1 WTO 
Message issued by segment: DPPXDPB 

Explanation: The BLKSIZE and LRECL (record length) specified on the 

DPBIN DD card is too small to contain the largest record 
on the data set. 

Response: The BLKSIZE and LRECL on the DPBIN DD card must be equal 
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to the maximum BLKSIZE and LRECL used when the data was 
recorded- 



DPP898 DATA SET NOT OPEN FOR DDNAME cccccccc. ROOTE CODES 

WHICH SPECIFY THIS DDNAME OUT OF SERVICE 

Routing code: The message is issued as an 0S/VS1 WTO 

Message issued by segment: DPPdINIT 

Explanation: The specified DD name was defined in the message routing 
code table (RCT) during SYSGEN by the MSGRC macro, but 
no DD card with that name could be found in the JCL. 
ALL routing codes referencing the specified DD name are 
put out of service. 

Response: A DD card with the specified DD name should be placed 

in the JCL. 
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OFFLINE U TILI TY HESSAGES 

DPPXDB01 DATA BASE FINAL PHASE PROCESSOR ENTERED 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: The data base final phase processor has been successfully 
entered through execution of a LINK supervisor call by 
the Offline Utility. 

Response: None, 

DPPXDB02 INSUFFICIENT DIRECTORY SPACE ALLOCATED 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAT 

Explanation: The data base partitioned data set does not have enough 
directory blocks allocated to hold all the arrays being 
added to the data base. The data base remains as it 
was prior to this execution of the data base final phase 
processor. Test mode is set and a return code of 12 is 
returned on completion. 

Response: The data base partitioned data set must be either: 

• Scratched and reallocated with a larger number of directory blocks 
specified, or 

• Copied to a new data set which has been allocated with a larger 
number of directory blocks allocated. 

DPPXDB03 DATA BASE FINAL PHASE PROCESSOR COMPLETION CODE = XX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: The data base final phase processor has completed 
execution and is returning control to the Offline 
Utility. XX is a return code with the following 
meanings : 

Code Desc ri ptio n 

,00 Successful completion. 

OU An error, indicated by previous messages, has occurred 

but processing continued. 

08 No arrays defined for this control card. 

12 Test mode set — An explanation exists in previous 

messages. 

16 The data set defined by the DBINIT DD card could not be 

opened . 

The data base is modified only if the return code is 00 or 04. For 



Description and Operation Manual 



any other return code, the data base remains as it was prior to this 
execution of the data base final phase processor. 



Response: If the return code is not 00, make the changes necessary 

to correct the errors indicated by messages or the return 
code. 

DPPXDB04 INVALID OPTIOH RECEIVED - TEST MODE ASSUMED 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: The processing mode specified is not ADD, REPL, DEL, or 

TEST, so the default mode of TEST is assumed. No changes 
are made to the data base. A return code of 12 is 
returned on completion. 

Response: Correct the OPTION= operand on the Offline Utility 

control card and rerun the job. 

DPPXDB05 NO ARRAYS DEFINED - NO PROCESSING PERFORMED 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: The input to the data base final phase processor did 
not define any arrays; therefore, no processing could 
be performed. A return code of 08 is returned on 
completion . 

Response: Correct input and rerun the job. 

DPPXDB06 NO PROCESSING FOR DUP ARRAY NAME - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name or number as specified on the 
NAME=or NDMBER= operand of the ARRAY macro. 

An attempt has been made to add the named array to the 
data base, but an array with the same name already exists 
on the data base. Processing for the named array is 
bypassed, and a return code of OU is set on completion 
of execution of the data base final phase processor. 

Response: Change the name of the array named in the message and 

rerun the job. 

DPPXDB07 UNABLE TO OPEN DATA BASE DDNAME - DBINIT 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: The data base partitioned data set defined by the DBINIT 
DD card cannot be opened. No processing is performed, 
and a return code of 1 6 is returned on completion. 
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Response: 



Correct the DBINIT DD card and rerun the job. 



DPPXDB08 TEST MODE SET ~ DO P ITEM NAME - XXXXXXXX 

Pouting code: SYSPRINT 

Message issued by segment: DPPXDBAT 

Explanation: XXXXXXXX is an Item name as specified on the NAME= 
operand of the ITEM macro. 

An attempt has been made to add the named item to the 
data base, but an item with the same name already exists 
on the data base. The remainder of the input is 
processed in TEST mode, and the data base will remain 
as it was prior to this execution of the data base final 
phase processor. A completion code of 12 is returned 
on completion. 

Response: Change the name of the ITEM being added to the data base 

or delete the existing data base array that contains 
the item name being duplicated. 



DPPXDB09 DATA SIZE GT BLKSIZE - TRUNCATION FOE ARRAY NAME - 

XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name. The amount of data specified 
for a block in the named array is greater than the array 
block size defined on the ARRAY macro. The data is 
truncated to the array block size and processing is 
continued. A return code of 04 is returned on 
completion- 
Response: Increase the array block size, or reduce the amount of 
data for the named array, and rerun the job. 



DPPXDB10 ARRAY BLOCK SIZE REDUECED TO DATA SET SIZE FOR ARRAY - 

XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name. The array block size for 

the named array is greater than the data base data set 
block size. The array block size is reduced to the data 
set block size, and processing is continued. A return 
code of 04 is returned on completion. 

Response: Reduce the array block size or reallocate the data set 

with a larger block size and rerun the job. 
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3PPXDB1 1 
Routing code: 
Message issued 
Explanation : 

Response : 

DPPXDB12 
Routing code: 
Message issued 
Explanation : 

Response: 

DPPXDB13 
Routing code: 
Message issued 
Explanation: 

Response : 

DPPXDB1U 
Routing code: 
Message issued 
Explanation: 

Response : 

DPPXDB15 
Routing code: 
Message issued 
Explanati on : 

Response: 



ARRAY ADDED - XXXXXXXX 
SYSPRINT 

by segment: DP PX DBAS 

XXXXXXXX is an array name. The named array has been 
added to the data base. 

None. 



ARRAY DELETED ~ XXXXXXXX 
SYSPRINT 

by segment: DPPXDBAS 

XXXXXXXX is an array name. The named array has been 
deleted from the data base. 

None. 



ARRAY REPLACED - XXXXXXXX 
SYSPRINT 

by segment: DPPXDBAS 

XXXXXXXX is an array name. The named array has been 
replaced on the data base. 

None. 



ARRAY TESTED IN REPLACE MODE - XXXXXXXX 
SYSPRINT 

by segment: DPPXDBAS 

XXXXXXXX is an array name. The named array was 
successfully processed in TEST mode as if a replace 
operation were being done. The data base is not 
modified . 



None. 



ARRAY NOT FOUND ~ XXXXXXXX 
SYSPRINT 

by segment: DPPXDBAS 

XXXXXXXX is an array name. An attempt was made to 
replace or delete the named array, but the array did 
not exist on the data base. 

When processing in DEL mode, ensure that the array name 
is correct. When processing in REPL mode, ensure that 
the array name is correct or that a ne w array is being 
added to the data base. 
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DPPXDB16 



BLOCK COONT EXCEEDED FOE ARRAY - XXXXXXXX 



Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name. The number of blocks of data 
specified on BLOCK macros for the named array is greater 
than the block count specified on the ARRAY macro. 
Excessive blocks of data will not be processed. A rerun 
code of OU Mill be returned on completion. 

Response: Increase the block count on the ARRAY macro, or reduce 

the number of blocks of data specified on BLOCK macros. 
After corrections are made, rerun the job. 



DPPXDB17 DUMMY BIT SET - NO PROCESSING FOR ARRAY - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name. The dummy bit has been set 
for the named array. The array will not be processed. 
There will be either another data base error message 
for the array or an MNOTE at the time the array was 
assembled. A rerun code of 04 will be returned on 
comp letion. 

Response: Correct the error indicated by a message or an MMOTE 

and rerun the job. 



DPPXDB18 RC=8 FROM BLDL - PERM I/O ERROR ON ARRAY - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name. A permanent I/O error 

indication has been returned by the BLDL SVC while trying 
to read the directory entry for the named array. 
Processing for this array is bypassed. A rerun code of 
OU will be returned on completion. 

Response: Determine and correct the cause of the I/O error and 

rerun the job. 

Note: Ensure that the data base partitioned data set has been allocated 
as a partitioned data set and not a sequential data set. 



DPPXDB19 TEST MODE ENTERED - DUPLICATE ARRAY IN INPUT - XXXXXXXX 

IN INPUT - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBAS 

Explanation: XXXXXXXX is an array name. The input contains two arrays 
with the same name. Processing will continue in test 
mode, and a rerun code of 12 will be returned on 
completion. 
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Response: 



Correct the array names and rerun the job. 



DDPXDB25 TEST MODE ENTERED - UNABLE TO OPEN DDNAME - XXXXXXXX 

OPEN DDNAME - XXXXXXXX 

Routing code:: SYSPRINT 

Message issued by segment: DPPXDBLG 

Explanation: XXXXXXXX is a DD name for a data base BDAM data set. 

The named DD The named DD statement could not be opened 
for data base processing- The remainder of the input 
is processed in test mode. The data base is not modified 
by this execution, A return code of 12 will be returned 
on completion. 

Response: Correct the DD statement or the ARRAY macro that 

specified the ddname and rerun the job. 

DPPXDB35 RON ABORTED - UNABLE TO OPEN ddname - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment - DPPXDBCP 

Explanation: XXXXXXXX is the name of a DD statement. The named DD 

statement is required for the execution of the COMPRESS 
No processing is performed. 

Response: Correct the DD statement and rerun the job. 

DPPXDB36 INVALID DATA BASE DATA SET: ddname - DBINIT 

Routing code: SYSPRINT 

Message issued by segment - DPPXDBCP 

Explanation: The data set described by the DBINIT DD statement is 
not a valid data base partitioned data set. No 
processing is performed. 

Response: Correct the DD statement and rerun the job. 

DPPXDB37 RC=8 FROM BLDL - PERM I/O ERROR 

Routing code: SYSPRINT 

Message issued by segment - DPPXDBCP 

Explanation: A permanent I/O error indication was returned by the 

BLDL SVC while processing the DBINIT DD statement. No 
processing is performed. 

Response: Determine and correct the cause of the I/O error and 

rerun the job. 

Note: Ensure that the DBINIT DD statement describes a partitioned data 
set and not a sequential data set. 
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DPPXDB38 DATA BASE DOES NOT CONTAIN DIRECT ACCESS ARRAYS 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBCP 

Explanation: No compress operations can be performed, since the data 
base contains no direct access arrays. 

Response: None. 

DPPXDB39 DATA BASE COMPRESS COMPLETED FOR ddname - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DDPXDBCP 

Explanation: XXXXXXXX is a DD statement name. The data base BDAM 
data set described by the named DD statement has been 
compressed, and all appropriate changes have been made 
to the PDS described by the DBINIT DD statement- 
Response: None. 



DPPXDBt^O THE SPECIAL REAL TIME OPERATING SYSTEM DATA BASE 

BDAM DATA SET COMPRESS 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBCP 

Explanation: This message indicates that the data base BDAM data set 
compress program has started execution. 

Response: None. 



DPPXDBU1 ****** END OF DATA BASE BDAM DATA SET COMPRESS ****** 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBCP 

Explanation: This message indicates that the data base BDAM data set 
compress program has completed execution. 

Response: None. 



DPPXDB42 NO DD STATEMENT INCLODED FOR ddname - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DDPXDBCP 

Explanation: XXXXXXXX is a DD statement name. The data base contains 
direct access arrays which are referenced by the named 
DD statement, but the JCL does not contain the DD 
stateasent. The data set referenced by the named DD 
statement is not compressed. 

Response: Include the DD statement in the JCL and rerun the job. 
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DPPXDB50 



TEST MODE ENTERED 



- DNABLE TO OPEN ddname - 



xxxxxxxx 



Routing code: SYSPRINT 

Message issued by segment: DDPXDBDA 

Explanation: XXXXXXXX is a DD name for a data base EDAM data set. 

The named DD statement could not be opened for data base 
processing. The remainder of the input is processed in 
test mode. The data base is not modified by this 
execution. A return code of 1 2 will be returned on 
completion. 

Response: Correct the DD statement or the ARRAY macro which 

specified the DD name and rerun the job. 



DPPXDB51 TEST MODE ENTERED - NO PROCESSING FOR ONBLOCKED DA ARRAY 

XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBDA 

Explanation: XXXXXXXX is an array name. The array macro for the 

named array specified the operand LOCATE=DA but describes 
the array as unblocked. The array cannot be processed, 
since all DA arrays must be blocked. The remainder of 
the input is processed in TEST mode, and the data base 
is not modified by this execution. A return code of 12 
is returned on completion. 

Response: Correct the array macro and rerun the job. 



DPPXDB52 ABRAY BLOCK SIZE REDUCED TO DATA SET BLOCK SIZE FOR 

ARRAY - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBDA 

Explanation: XXXXXXXX is an array name. The array block size for 

the named array is greater than the data base data set 
block size. The array block size is reduced to the data 
set block size and processing is continued. A return 
code of OU is returned on completion. 

Response: Reduce the array block size or reallocate the data set 

with a larger block size and rerun the job. 



DPPXDB53 DATA SIZE GT BLKSIZE - TRUNCATION FOR ARRAY NAME - 

XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDBDA 

Explanation: XXXXXXXX is an array name. The amount of data specified 
for a block in the named array is greater than the array 
block size defined on the ARRAY macro. The data is 
truncated to the array block size and processing is 
continued. A return code of OU is returned on 
CO mpletion. 
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Response: 



Increase the array block size or reduce the amount of 
data for the named array and rerun the job- 



DPPXDBSa BLOCK COUNT EXCEEDED FOR ARRAY - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment - DPPXDBDA 

Explanation: XXXXXXXX IS AN ARRAY NAME. The number of blocks of data 
specified on BLOCK macros for the named array is greater 
than the block count specified on the ARRAY macro. 
Excessive blocks of data will not be processed. A return 
code of 04 will be returned on completion. 

Response: Increase the block count on the ARRAY macro or reduce 

the number of blocks of data specified on BLOCK macros. 
After corrections are made, rerun the job. 



DPPXUT01 MISSING DDCARD - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: XXXXXXXX is a DD statement name. The named DD statement 
is required but is not included in the JCL. DD 
statements may be required because it is specified on 
the INPUT= operand of the control card or may be required 
for offline utility execution. 

Response: Correct the control card or DD statement name and rerun 

the job. 



DPPXUT02 FIRST CARD MUST BE A CONTROL CARD 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The first card read from the SYSIN data set must be a 
valid offline utility control card. If it is not, no 
processing will be done. 

Response: Correct the SYSIN input and rerun the job. 



DPPXUT03 PARAMETER OR CONTINUATION MARK MISSING 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The control card being processed is missing a required 
parameter, or a continuation mark is missing if the 
control card is continued on another card. Processing 
for this control card is bypassed. Processing will 
commence with the next control card. 

Response: Correct the control card and rerun the job- 
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DPPX0T04 EXPECTED CONTINUATION NOT RECEIVED 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The control card being processed indicated that a 

continuation card existed but no continuation card was 
received. Processing will continue with the next control 
card . 

Response: Correct the control card and rerun the job. 



DPPXUT05 COLUMNS 1-15 MUST BE BLANK 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: Card columns 1 through 15 must be left blank on control 
card continuations, on control card continuations. 
Processing will continue with the next control card. 

Response: Correct the control card and rerun the job. 



DPPXUT06 CONTROL CARD TEXT BEYOND COL 71 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The text of a control card must not extend past card 

column 71. If more space is needed, then continuation 
cards must be used. Processing will continue with the 
next control card. 

Response: Correct the control card and rerun the job. 



DPPXUT07 WRONG PARAMETER: XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: XXXXXXXX is the parameter in error. An invalid value 

has been specified for one of the operands on the control 
card. Processing will continue with the next control 
card- 
Response: Correct the control card and rerun the job. 



DPPXUT08 MULTIPLE KEYWORD: XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: XXXXXXXX is a keyword operand on the offline utility 
control card. The named keyword operand has been 
specified more than once on the same control card. 
Processing will continue with the next control card. 
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Response: Correct the control card and rerun the job. 

DPPXUT09 PARAMETER IN ERROR: XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXOTIL 

Explanation: XXXXXXXX is a parameter specified on the offline utility 
control card. The named parameter is invalid. 
Processing will continue with the next control card. 

Response: Correct the parameter and rerun the job. 

DPPXUT10 RIGHT PARENTHESIS MISSING - TREATED AS VALID 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: One of the parameters on the offline utility control 

card was started with a left parenthesis but not ended 
with a right parenthesis. with a right parenthesis. 
Processing continues as if the right parenthesis were 
present. 

Response: Correct the control card. 

DPPXUT11 WRONG KEYWORD: XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: XXXXXXXX is a keyword operand on an offline utility 
control card. The named keyword operand is invalid. 
Processing will continue with the next control card. 

Response: Correct the control card and rerun the job. 

DPPXUT12 INPOT SPECIFICATION MISSING 

Routing code: SYSPRINT 

Message issued by segment: DPPXOTIL 

Explanation: The INPUT= operand is required on the DPPXOCTL control 

card, but it has been omitted. Processing will continue 
with the next control card. 

Response: Correct the control card and rerun the job. 

DPPXUT13 AREA SPECIFICATION MISSING 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The AREA= operand is required on the DPPXUCTL control 
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card, but it has been omitted. Processing will continue 
with the next control card. 

Response: Correct the control card and rerun the job, 

DPPX0T15 NEW SET SPECIFICATION MISSING 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The NEW SET= operand is required on the DPPXUPDT control 
card, but it has been omittted. Processing will continue 
with the next control card. 

Response: correct the control card and rerun the job, 

DPPXUT16 OLDSET SPECIFICATION MISSING 

Routing code: SYSPRINT 

Message issued by segment: DPPXOTIL 

Explanation: The OLDSET= operand is required on the DPPXUPDT control 
card, but it has been omitted. Processing will continue 
with the next control card. 

Response: Correct the control card and rerun the job. 

DPPX0T17 NO OPERAND FOUND 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: A DPPXUPDT or DPPXUCTL control card has been encountered, 
but no operands were specified. Processing will continue 
with the next control card. 

Response: Correct the control card and rerun the job. 

DPPXUT18 INVALID OPERATION 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: An offline utility control card has been encountered, 
but the operation field is invalid. Processing will 
continue with the next control card. 

Response: Correct the control card and rerun the job. 

DPPXUT19 NO OPERATION FOUND 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 
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Explanation: An offline utility control card has been encountered, 
but no operation or operands have been specified. 
Processing will continue with the next control card. 

Response: Correct the control card and rerun the job. 

DPPXDT20 SYSIN END-OF-FILE 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: An end -of- file has been encountered on the data set 
described by the SYSIN DD statement. 

Response: None. 

DPPX0T21 CONTROL CARD INVALID, SKIPPING FOR NEXT CONTROL CARD 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: An invalid offline utility control card has been 

encountered, and processing will continue with the next 
control card. 

Response: Correct the control card and rerun the job. 

DPPXUT22 ****** THE SPECIAL REAL TIME OPERATING SYSTEM OFFLINE 

UTILITY DPPXUTIL ****** 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The Special Real Time Operating System offline utility 
program has started execution. 

Response: None. 

DPPXUT23 ****** END OF THE SPECIAL REAL TIME OPERATING SYSTEM 

OFFLINE UTILITY DPPXUTIL ****** 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The Special Real Time Operating System offline utility 
program has completed execution. 

Response: None. 

DPPXUT24 END-OF-FILE ON INPUT DATA SET 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 
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Explanation: An end-of-file has been reached on the input data set 

described by the INPDT= operand of the DPPXUCTL control 
card. 

Response: None. 



DPPXUT25 PARK FIELD INVALID - P ARM= » NOGEN • ASSOMED 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation: The value specified in the PARM field of the execute 
card is invalid. The default PARM value of 'F^NOGEN* 
will be assumed. 

Response: correct the PARM field on the EXEC card and rerun the 

job. 



DPPXUT26 PROCESSING ABORTED DUE TO BAD RETURN CODE FROM - XXXXXXXX 

Routing code: SYSPRINT 

Message issued by segment: DPPXDTIL 

Explanation: XXXXXXXX is either ASSEMBLY or LOADER. A return code 
of 8 or greater from %h.e assembler or from the loader 
will cause processing to be aborted for the current 
control card. Processing will continue with the next 
control card. 

Response: Correct the errors indicated by the assembler or the 

loader and rerun the job. 



DPPXUT99 CONTROL CARD ACCEPTED 

Routing code: SYSPRINT 

Message issued by segment: DPPXUTIL 

Explanation : The current control card has been accepted by the offline 
utility program for processing. 

Response: None. 
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hRRMUll-h- THE SPECIAL REAL-TIM E OPERATING SYSTEM SAMPLE PROGRAM 



The Special Real Time Operating System Sample Program provides a minimal 
test of the functioning of the Special Real Time Operating System. It 
also provides a demonstration of the Special Real Time Operating System. 
It can be used as an example and training tool, as well as an 
instructional aid for application program education. The sample program 
consists of two programs (DPPZSAMP, DPPSAMP1). 

DPPZSAMP will test and provide examples of the following Special Real 
Time Operating System subsystems: 

Task Management (PATCH Macro) 

Data Base Management (GETARRAY, GETITEM, PUTARRAY, PUTITEH, 

GETLOG and PUTLOG Macros) . 
TIME Management (PTIME Macro) 
Realtime Message Handler (MESSAGE Macro) . 

DPPZSAMP will require the following array (DPPZSAMP) to be built by 
the Special Real Time Operating System Offline Utility: 



#/ DPPXUCTL AREA=DBDEF, INPUTS*, OPTION=ADD 

ARRAY NAME=DPPZS AMP, IN IT =Y ES , R EI NIT= Y ES, 

LOCATE=VS, L0GNAME = DPPSAMP1 , 

L0GDD=DBINIT2, LOGFREQ=0 



ITEM 


NAME 


=DPPSAMP2, TYPE 


=C, 


LEN 


= 6 ,INIT= 


ARRAY 


ITEM 


NAME^ 


=DPPSAMP3, TYPE 


= C, 


LEN 


=9 ,INIT= 


DPPZSAMP 


ITEM 


NAME 


=DPPSAMPU, TYPE 


=c. 


LEN 


= 3 ,INIT== 


IS 


ITEM 


NAME 


=DPPSAMP5, TYPE 


=c. 


LEN 


= 5 ,INIT= 


USED 


ITEM 


NAME 


=DPPSAMP6, TYPE 


=c. 


LEN 


= 3 ,INIT= 


BY 


ITEM 


NAME 


=DPPSAMP7, TYPE 


=c. 


LEN 


^6 ,INIT= 


SRTOS 


ITEM 


NAME 


=DPPSAMP8, TYPE 


=c. 


LEN 


=7 ,1 NIT= 


SAMPLE 


ITEM 


NAME 


=DPPSAHP9, TYPE 




LEN 


=8 ,INIT= 


PROGRAM 


ITEM 


NAME 


=DPPSAMP A, TYPE 


=C, 


LEN 


= H ,INIT= 


FOR 


ITEM 


NAME 


=DPPSAMPB,TYPE 


=c. 


LEN 


= 5 ,INIT= 


TEST 


ITEM 


NAME 


=DPPSAMPC, TYPE 




LEN 


=8 ,INIT= 


PURPOSES 
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The following example is typical of the JCL required to define the 
sample array. Following is a description of each of the JCL statements 
in the example. The underlined portions of the JCL will likely have 
to be changed by the user to suit the requirements of his operation. 



//BUILD 


JOB 


(ACCOUNTING INFORMATION) 


//SI 


EX EC 


PG M=DP PX UTIL , P ARM^H 


//STEPLIB 


DD 


DSN=USER.PROCLIB,DISP=SHR 


//SYSPRINT 


DD 


SYSOUT=A 


//ASMPRINT 


DD 


SYSOUT=A 


//LODPRINT 


DD 


DUMMY 


//SYSLIB 


DD 


DSN=DSER. M ACLI B, DISP=SHR 


// 


DD 


DSN=SYS1.H ACLIB, DISP=SHR 


//SYS DTI 


DD 


UNIT= (SYSD A,SEP=SYSLIB) ,SPACE= (CYL, (2,2) ) 


//SYSUT2 * 


DD 


UNIT= (SY$D A,SEP=SYSUT1) ,SPACE= (CYL, (2, 2) ) 


//SYS0T3 ♦ 


DD 


UNIT= (SYSDA,SEP=SYSUT1) ,SPACE= (CYL, (2,2) ) 


//SYSDT4 


DD 


UNIT= (SYSD A,SEP=SYSUT1) ,SPACE= (CYL, (2,2) ) 


// 




DCB= (RECFM=FB,LRECL=80,BLKSIZE=3200) 


//DDI NIT 


DD 


DS N= U S ERiD B1 # D I S P= OL D 


//DBINIT2 


DD 


DSN=USER.DB2,DISP= (MOD, PASS) ,DCB= (DSORG=DA) 


//SYSGO 


DD 


UNIT=SYSDA,SPACE=(CYL, (1,1) ) , 

DCB= (RECFM = FB,LRECL=80,BLKSIZE=3200) 


//SYSIN 


DD 





(Input Control Statements) 



JCL Example 

/♦ 

JOB 

Is a standard 0S/VS1 job card; the accounting information is dependent 
upon individual installation requirements. 

EXEC 

Is a standard 0S/VS1 EXEC card; it must specify PGM=DPPXUTIL or an 
applicable user PROC. 

PARM 

The offline utility will provide the option to print or not to print 
statements generated by the processing of a macro. This will be 
accomplished by the offline utility inserting or not inserting a PRINT 
NOGEN statement as the first statement in the Assembler SYSIN stream. 
Control will be provided through the PARM keyword operand on the 
execute card for DPPXUTIL, This option is provided in addition to 
the option to select the OS/VSl assembler or the H assembler. 

The following values may be specified: 



F — Selects the OS/VSl Assembler. 

H — Selects the H Assembler. 

GEN — Print macro generated statements. 

NOGEN — Do not print macro generated statements. 



In all cases, the default values will be "F" and "NOGEN". 



*Not required when "PARM=H" is specified on the execute card. 
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Valid combinations of the values are: 



FARM 


= 


I p I 


FARM 




•H • 


FARM 




•GEN« 


PARN 




•NOGEN' 


FARM 




•F,GEN» 


FARM 




•F, NOGEN* 


FARM 




•H,GEN« 


FARM 




•H, NOGEN' 



If an invalid value is specified for the FARM operand or if the FARM 
operand is omitted, the default of PARM=« F, NOGEN « will be used. 

STEFLIB DD 

Defines the library containing the DPFXOTIL program and final phase 
processors and is not required if these programs reside in SYS1 ,LINKLIB. 

SYSFRINT DD 

Defines a data set in vhich printed output will be placed, or may 
specify a standard output class. 

ASMPRINT DD 

(Same as SYSFRINT) for printed output from the assembler. 

LODPRINT DD 

(Same as SYSFRINT) for printed output from the loader. It is 
recommended that this be a DD DOHMY to reduce printed output. 

SYSLIB DD 

Defines the data set (s) containing the macros used by the assembler, 
SYSUTI DD 

Defines the assembler work data sets- SYSDA defines a direct-access 
device. This name (SYSDA), if This name (SYSDA), if used, must have 
been generated into the 0S/VS1 system. SEF= is specified to improve 
assembler performance. 

SYS0T2 DD 

(Same as SYSUTI) . Not required when "PARM=H" is specified on the 
execute card. 

SYSUT3 DD 
(Same as SYSIJT2) . 

SYSUTU DD 

Defines a work data set for DPFXOTIL. The DCB parameters must specify 
RECFM=FB and a BLKSIZE that is a multiple of 80. The LRECL must be 
80. 

DBINIT DD 

Defines the data base partitioned data set that contains a member for 
every array in the data base, control information for direct access 
resident arrays and initial data for VS resident arrays. This DD card 
is required if any utility control card specifies AREA=DBDEF. 

DBINIT2 DD 

Defines the BDAM data set which contains the initial data for DA 
resident arrays. This DD card is required if any utility control 
statement specifies AREA=DBDEF. The data set described by this DD 
card must be allocated prior to the execution of the The DISP= operand 
on this DD card must be specified as (MOD, PASS). 

SYSGO DD 
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Defines the data set to contain the object deck output from This data 
set is used as input to the 0S/VS1 loader. 

SYSIN DD 

Defines the input from which DPPXUTIL gets its control statements as 
possibly some source macro statements. 

The sample programs (DPPZSAMP and DPPSAMP1) are not copied to the target 
data sets at SYSGEN time. Therefore, to execute them, the user must 
copy them or use a STEPLIB DD card to allocate data set A5799AHE. OBJECT. 

The Special Real Time Operating System Sample Program can be executed 
by adding the following PATCH and WAIT input cards to the Special Real 
Time Operating System Subsystem Initialization Stream: 



PI PATCH TASK=DPPZSA MP,EP=DPPZSA MP 
WAIT PI 



The following 


exa mple 


is typical of the JCL required to execute the 


sample problem 






//REAL 


JOB 


3DE50 1^' PROGRAMMERljtCL ASS=F 


// 


EXEC 


PGn=DPPINIT 


//STEPLIB 


DD 


DSN = ACS370^M01, DISP=SHR 


//DBINIT 


DD 


D S N=ACS370 .DB1 , D IS P= SH R 


//DBINIT2 


DD 


D S N= AC S3 70 ^B2 , D IS P= SH R 


//MSGDS 


DD 


DSN=ACS370 .DBa,DISP=SHR 


//DPPFAIL 


DD 


DSN=ACS370 .FALRST, DISP=OLD 


//SYSPRINT 


DD 


SYSOUT=A 


//MSGOtJT 


DD 


SYSOUT=A 


//SYSUDUMP 


DD 


SYSOUT=A 


//SYSINIT 


DD 


* 



In the previous example, the JOB card is standard OS, and accounting 
information must be as required for the individual installation. The 
EXEC card must specify PGM-DPPINIT. The STEPLIB DD card points to the 
library (ies) containing the Special Real Time Operating System and user 
programs. The library name will depend upon the name given the data 
sets at SYSGEN time. The data sets required for the data base are 
pointed to by the DD cards DBINIT and DBINIT2. The online message 
handler requires the MSGDS and MSGOOT DD cards. The SYSPRINT DD card 
is required by initialization to print the input control statements. 
A SYSUDOMP or SYSABEND DD card is optional, depending on whether a dump 
is required on ABEND conditions. The SYSINIT DD card is required, and 
it must point to the data set containing the control statements for 
the online run. 



DPPZSAMP will issue the following messages, if all tested subsystems 
are functioning properly: 



DPP068I HH:MM:SS.rH DD/MMM/YY PATCH MACRO FONCTIONING 
DPP066I HH:MM:SS.TH DD/MMM/YY ARRAY DPPZSAMP IS USED BY 

SRTOS SAMPLE PROGRAM FOR TEST PURPOSES 
DPP068I HH:MM:SS.TH DD/MMM/YY PfJTLOG MACRO FUNCTIONING 
DPP066I HH:MM:SS.TH DD/MMM/YY ARRAY DPPZSAMP IS USED BY SRTOS 

SAMPLE PROGRAM FOR TEST PURPOSES 
DPP068I HH:MM:SS.TH DD/MMM/YY PUTARRAY MACRO FUNCTIONING 
DPP069I HH:MM:SS.TH DD/MMM/YY ITEM DPPSAMP2 CONTENTS ARE ARRAY 
DPP068I HH;MM:SS.TH DD/MMM/YY PUTITEM MACRO FUNCTIONING 
DPP068I HH:MM:SS.TH DD/MMM/YY PTIME MACRO FUNCTIONING 



The only function of DPPSAKP1 is to issue messages. It is used to 
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EXTERNAL SYMBOL DICTIONARY 



SYMBOL TYPE ID AODR LENGTH LD ID 
DPPZSAHP SD 0001 000000 0004AC 



ASM H V 0* 09. 15 11/04/75 



LOC OBJFCT CODE 



SAMPLE PROGRAM 



AOORl AD0R2 STMT SOURCE STATEMENT 



PAGE 



ASM H V 04 09.15 11/04/75 



18 
19 
?.0 
Zl 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
43 
49 
50 
51 
52 
53 



itt *********** 

* MODULE NAME =DPPZSAMP * 

* DESCRIPTIVE NAME = SPECIAL R?AL TIME OPERATING SYSTEM SAMPLE PROGRAM* 

* FUNCTION = OPPZSAMP fUNCTiCJN IS TO PROVIDE A MINIMAL TEST OF THE * 

* FUNCTIONING OF THE SPFCIAL KEAL TIME OPERATING SYSTEM. • 

* NOIES = IT ALSO PROVIDES 4 DEMONSTRATION AND CAN BE iJSED AS A ♦ 
» TRAINING TOOL FOR APPLICATION PROGRAM EDUCATION. * 

* DEPENDENCIES = ARR AV • OPPZS AM?' MUS I BE GENERATED BY THE USER . A * 

* DESCRIPTION OF THE ARRAY CAN BE FOUND IN THE SPECIAL REAL TIME ♦ 

* OPERATING SYSTEM DOM APPENDIX 1 * 

* RE STRI CTI ONS = NONE * 

* REGISTER CONVENFIGNS = ALL REGS ARE ASSIGNED AS $R WHERE REGS 0-15 ♦ 
» ARE t0-il5 * 

* MODULE TYPE = SAMPLE PROGRAM * 

* PROCESSOR = ASSEMBLER F * 
» MODULE SIZE = 1192 DECIMAL BYTES * 

* ATTRIBUTES = REENTRANT * 

* ENTRY POINT = OPPZSAMP * 

* INPUT = ARRAY OPPZSAMP * 

* OUTPUT = SPECIAL REAL TIME OPERATING SYSTEM MESSAGES 68 , 66 , 69 * 

* RETURN = NORMAL OS/VS RETURN. NO RETURN CODES ♦ 

* EXTERNAL REFERENCES * 

* ROUTINES = DPPSAMPl ♦ 

* DATA AREAS = SPECIAL REAL TIME OPERATING SYSTEM DATA BASE ♦ 

* (ARRAY OPPZSAMP) * 
» CONTROL BLOCKS = XCVT * 

* TABLES = NONE * 

* MACROS = BEGIN, EX IT, ME SSAGE , PA TCH.GETARRAY, PUTLOG, GE TLOG, PUTARRAY , ♦ 

* GETITEM.PUTITEM.PT IME ♦ 

**♦*♦»**♦♦*»♦:♦*»*»****♦«**»************«•**********♦*♦*******»**»**♦**»* 

* ♦ 

»* THE BEGIN MACRO WILL ESTAB4, ISH AN ENTRY POINT FOR THE 

»» SAMPLE PROGR AM(DPPZSAMP) , A BASE RE G I S T E R ( 8 A S E =) AND SAVE ** 

** THE CALLING PROGRAM R E G I S TER S ( S A V E A= AND LV=) 

* 

BEGIN DPPZSAMP,SAVEA=(GErMAlN,WQRK) ,6AS£=(12) ,LV=7 2 
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'MAIN' CONTROL SECTION 



00002000 
00002100 
00002200 
00003000 
00003100 
00003200 
00004000 
00004100 
00004200 
00005000 
00005100 
00005200 
00006000 
00006 100 
00006200 
00007000 
00007 100 
00007200 
00008000 
00008100 
00008200 
00008300 
00008400 
00008500 
00008600 
00008700 
00008800 
00008900 
00008910 
00008920 
00009000 
00010000 
0001 1000 
00012000 
00013000 
00014000 
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PAGE 3 


LOC 


ORJFCT CODE AOORl AD0R2 


STMT SOURCE 


STATEMENT 


ASM H V 04 09, 


15 11/04/75 








56»* 






GOES THRU REGISTER EQUATE ONLY ONCE 








00000 


57 +$0 


EQU 


0 ? 


** 


02-EOUAT 






OOOOl 




EQU 


1 ? 


** 


02-EQUA T 






00002 


59 + $2 


EQU 


2 7 


• * 


02-EQUAT 






00003 


60+t3 


EOU 


3 7 




02-EQUAT 






00004 


614-54 


EOU 


4 ? 




02-EOUA T 






00005 


624-S5 


EQU 


5 ? 




02-EQUAT 






00006 


63'*' S 6 


EOU 


6 ? 


•♦IF THESE SUBSTITUTES ARE USED AS 


02-E&UAT 






00007 


64 v$ 7 


EQU 


7 ? 


••REGISTER NUMBERS THE CROSS-REFERENCE 


02-EOUAT 






00008 


65 + J8 


EQU 


8 ? 


•♦TABLE WILL PROVIDE A LIST OF WHERE 


02-EQUAT 






00009 


66«'$ 9 


EQU 


9 ? 


♦♦EACH REGISTER WAS USED 


02-EQUA T 






OOOOA 


67+$l0 


EOU 


10 ? 


♦ « 


02-EOUAT 






OOOOB 


68+ tl I 


EOU 


1 1 7 


♦ • 


02-EQUAT 






OOOOC 


69+ $12 


EOU 


12 ? 


♦♦ 


02-EQUA T 






00000 


70+$l3 


EOU 


13 ? 


♦ ♦ 


02-EOUAT 






OOOOE 


71+$14 


EOU 


14 ? 


*♦ 


02-EQUAT 






OOOOF 


72*t 15 


EQU 


15 ? 


♦ ♦ 


02-EOUAT 






00000 


73 +FkPO 


EQU 


0 




02-EQUAT 






00002 


74«-F PR2 


EQU 


2 




02-EOUAT 






00004 


75*FPR4 


EQU 


4 




02-EOUAT 






00006 


76*FPR6 


EQU 


6 




02-EQUAT 


000000 






78* 


OS 


00 . 


FOR BOUNDARY ALIGNMENT 


0 I- 8 £ G I N 






00000 


79 + 


USING 


•,15 . 


TEMPORARY BASE DECLARATION 


01-8EGIN 


000000 




FOOE OOOOE 


80+ 


B 


14(0, 15 ) 


BRANCH AROUND ID 


02- SA VE 


000004 


08 




81* 


DC 


ALU 81 


LENGTH OF IDENTIFIER 


0 2- S A V E 


000005 


C407D7E<)E2C1DA07 


82 + 


DC 


CL8'DPPZSAMP 1 


1 IDENTIFIER 


02-SAVE 


000000 


00 














OOOOOE 


90FC 


OOOC OOOOC 


8i* 


STM 


14,12. 12( 131 


SAVE REGISTERS 


02-S AVE 


0000 I 2 


5800 


F034 00034 


84 ^ 


L 


O.TKGOOOIG 


LOAD SP AND LV PARAMETERS 


01-BE6I N 








8 5«-* 


GETMAIN R,LV=10» 






000016 


<»510 


FOIA OOOIA 


86 + 


8AL 


I, * + 4 


INDICATE GETMAIN 


02-GETMA 


OOOOIA 


OA OA 




87 + 


SVC 


10 


ISSUE GETMAIN SVC 


02-GETMA 


0000 1 c 


5001 


0004 00004 


88+ 


ST 


13,4(1) . 


SAVE CALLER'S SAVE AREA POINTER 


01-BEGIN 


000020 


501D 


0008 00008 


89 ♦ 


ST 


1,8(13) . 


FOR DOWNWARD SAVE AREA TRACE 


Ol-BEGIN 


00002<t 


ISO I 




90+ 


LR 


13,1 . 


ESTABLISH OWN SAVE AREA POINTER 


Ol-BEGIN 


000026 


5810 


0004 00004 


91 + 


L 


1,4(13) . 


RESTORE 15,0,1 


Ol-BEGIN 


00002A 


0«E 1 


lOOC OOOOC 


92 + 


LM 


14,1, 12( L) 


RESTORE GET REGS 


Ol-BEGIN 


000000 






94+ WORK 


□SECT . 


BEGIN GETMAINED AREA 


Ol-BEGIN 


000000 






95 + 


OS 


9D . 


OWN SAVE AREA 


Ol-BEGIN 


00002E 






96+DPP2SAMP 


CSECT 






Ol-BEGIN 






00000 


97+ 


USING 


WORK ,1 3 




Ol-BEGIN 


00002E 


0 700 




99 + 


CNOP 


0,4 




Ol-BEGIN 


000030 


45C0 


E038 00038 


100+ 


BAL 


12,*+8 


ESTABLISH INITIAL 'MAIN' CSECT BASE 


Ol-BEGIN 


00003* 






lOl+TKGOOOlM 


OS 


OF . 


BASE REFERENCE 


Ol-BEGIN 


00003A 


00000048 


102+TKGOOOlG 


OC ALU0>,AL3t72) . SUBPOOL. LENGTH 


Ol-BEGIN 








103+ 


DROP 


15 




Ol-BEGIN 






00034 


104 + 


USING 


TKG0001M,12 




Ol-BEGIN 








105 * 






* 


00015000 








106 •» UPON 


ENTRY 


PASS 


PARAMETERS TO OPPZSAMP AS FOLLOWS : ♦* 


00016000 



107 
108 



♦ ♦•♦♦♦♦♦4r«*^4<* 

•RESIGISTER 1» > 



^^^t ************** 
* XCVT ♦ 



00017000 
00018000 



OPPZS&MP SAMPLE PROGRAM 



LOC 


OBJECT CODE AOORl 


A00R2 


STMT 


SOURCE STATEMENT 


ASH H V 


04 09. 15 


11/04/75 










109 *♦ 


♦RESOURCE TABLE • 


♦ ♦ 


00019000 










110 




♦PATCH PARAMETERS* 


♦ ♦ 


00020000 










111 ** 




♦ ♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦4[ 


♦ « 


0002 lOOC 










IIZ * 








♦ 


00022000 


000038 


5821 


0000 


00000 


113 


L »Z 


.0((1) 


PLACE XCVT ADDRESS IN 


REG 2 


00023 000 










1 14 * 








♦ 


000 24000 










115 *♦ 


THE FOLLOWING PATCH MACRO WILL 


CREATE AN INDEPENOANT TASK 


♦ 


00025000 










116 ** 


NAMED (TASK= 


) OPPSAMPl . THE TASK ENTRY P0INTIEP=> IS OPPSAMPl^^ 


0 0026000 










117 *» 


note: THE OCVTR OR OCVTLOC OPERAND SHGULO BE USED ON ONLINE 


** 


00027000 










118 ** 


MACROS TO INCREASE THEIR 


OPERATION EFFICIENCY . OCVTR 


♦ ♦ 


00028000 










119 ** 


AND OCVTLOC 


POINTS TO THE 


XCVT. 


♦ ♦ 


00029000 










120 * 








♦ 


00030000 










121 


PATCH 


T ASK=DPPSAMP1, EP= OPPS AMP 1 , DCVTR= ( %2) 




00031000 


00003C 


4110 


COlO 


00044 


122+ 


LA 


1 ,IHB0005 


SET UP PARAM LIST ADDRESS 




Ol-PATCH 


0000*0 


47F0 


C03C 


00070 


123 + 


B 


IH80005A 


BRANCH AROUND LIST 




Ol~PATCH 


00004* 








124+IHB0005 OS 


OF 






0 l-PATCH 


000044 


C4D7 07f:2Cl04D7Fl 




125+ 


DC 


CLB'OPPSAMPl • 


TASK NAME 




Ol-PATCH 


00004C 


C4D707E2C104D7FI 




126 + 


DC 


CLS'DPPSAMP 1 • 


ENTRY POINT NAME 




Ol-PATCH 


000054 


40404040 40404040 




127+ 


DC 


CL8» • 


PkTY REFERENCE NAME 




Ol-PATCH 


00005C 


00 






128 + 


DC 


AL U 0) 


FLAG BYTE 




Ol-PATCH 


0000 50 


01 






129 + 


OC 


AL 1 ( 1 ) 


OUEUE LENGTH 




Ol-PATCH 


00005E 


0000 






130+ 


DC 


H» 0* 


PRTY RELAT IVE VALUE 




Ol-PATCH 


000060 


00000000 




131 + 


OC 


A( 0) 


EC8 ADDRESS 




Ol-PATCH 


000064 


0000000000000000 




132+ 


OC 


2F'0' 


FREE LENGTH, FREE ADDRESS 




Ol-PATCH 


00006C 


00000000 




133+ 


DC 


A< 0) 


TCBX 




Ol-PATCH 








00070 


134+IH3O005A EOU 


♦ 






Ol-PATCH 


000070 


41F0 


C044 


00078 


135+ 


LA 


15,IHF0005 


SET UP LIST ADDRESS 




Ol-PATCH 


000074 








136 + 


CNOP 


0,4 






Ol-PATCH 


000074 


4500 


C 048 


0007C 


137 + 


BAL 


0, IHP0005A 


SET UP REG 0 WITH PARAM LIST 




Ol-PATCH 








00078 


138+IHP0005 EQU 


* 






Ol-PATCH 


000078 


0004 






139 + 


OC 


AL 21 IHP0005A-IHP0005I LENGTH OF PARAHS 




Ol-PATCH 


00007A 


0000 






140 + 


DC 


AL2(0J 


ID 




Ol-PATCH 








0007C 


141+IHP0005A EQU 


* 






Ol-PATCH 


00007C 


18F2 






142 + 


LR 


15, ( $2) 


C VT ADDRESS 




02-0PPSV 


00007E 


8FF8 


C051 


00085 


143 + 


ICM 


I5,8,*+7 


ID IN HIGH ORDER BYTE OF REG 




02-0PPSV 


000082 


4700 


0004 


00004 


144 + 


NOP 


4 


CONSTANT FOR ID 




02-DPPSV 


000086 


440F 


0004 


0 0004 


145 + 


EX 


0,4( 15) 


EXECUTE SVC FROM CVT 




02-OPPSV 










146 


IF RETURN CODE FROM PATCH SVC 


IS ZERO THEN 


♦ ♦ 


00032000 










147 


IF F , 


< $15» ,1 S, ZERO.THEN 






00033000 


00008A 


12FF 






148 + 


LTR 


$15, $15 






01-IF 


00008C 


4770 


COAO 


0000 4 


149+ 


BC 


7, IF10007 






01- IF 










150 ♦* 


OUTPUT MESSAGE 68 


, WHICH CONTAINS MSGl ( V AR= ) , TO 




00034000 










151 ** 


THE SYSTEM 


CON SOLE! ROUT E=l ). 




♦ ♦ 


00035000 










152 


MESSAGE 68,VAR=(MSG1) , 


DCVTR=($2),R0UTE=1 




00036000 


000090 








153 + 


CNOP 


0,4 






01-MESSA 


000090 


4510 


C070 


000A4 


154+ 


BAL 


1 , MS GOOD 8 






01-ME SSA 


000094 


01 






155+ 


OC 


AL 1( O+l) 


VARIABLE COUNT 




Ol-MESSA 


000095 


01 






156 + 


DC 


AL 1 1 1 1 


ROUTING CODE COUNT 




Ol-MESSA 


000096 


0000 






157+ 


DC 


AL2(0» 


MESSAGE NUMBER 




Ol-MESSA 


000098 


00 






158 + 


OC 


X'OO" 


ACTION CODE 




Ol-MESSA 


000099 


000000 




159 + 


OC 


AL3(0I 


USER RETURN AREA 




Ol-MESSA 


00009C 


0000 






160+ 


OC 


AL2(0J ROUTING CODE 




Ol-MESSA 


00009E 


00000000 




161 + 


DC 


1AL4( 0» 


MESSAGE VARIABLE 




Ol-MESSA 


0000A4 








162+MSG0008 OS 


OF 






Ol-MESSA 


0000 A4 


4100 


0044 


0 0044 


163 + 


LA 


0,68 LOAD MSG 


# INTO REGISTER 0 




Ol-MESSA 



SAMPLE PROGRAM 



PAGE 



O 
(t) 

CO 

O 

n 

n- 

o 
s 

p 

3 

o 

(D 

n 
ft 

H- 
O 



5.0C 


OBJECT CODE ADDRl 


A OCR 2 


STMT 


SOURCE 


STATEMENT 


ASM H V 04 09 „ 15 


11/04/75 


000OA8 


4001 


0002 


00002 


164 + 




STH 


Ot 2( 1 J MOVE MSG 


e TO PARAMETER LI ST 




01-MESS A 


OOOOAC 


4100 


0001 


00001 


165* 




LA 


0,1 LOAD ROUT ING 


. CODE INTO REGISTER 0 




01-MESSA 


0000 80 


4001 


0008 


00008 


166 + 




STH 


0,8JU STORE ROUTING CODE INTO PARAMETER LIST 




01-MESS A 


OOOOS* 


<?680 


1003 00008 




167* 




01 


8 1 IJ ,X« 80' 


SET HIGH BIT OF LAST ROUTINE 


CODE 


01-SE SSA 


0000 88 


IBFF 






168* 




SR 


15,15 


ZERO REG 15 FOR IC 




Ol-ME SSA 


OOQOB A 


43FI 


0001 


0000 1 


169* 




IC 


15, l{ 1 > 


# OF ROUTE COOES IN PARAMETER 


LIST 


01-MESSA 


00008 E 


8^F0 


0001 


0 0001 


170* 




SLL 


15 ,1 


LENGTH OF ROUTE CODE IN PARAf-i! 


LIST 


0 1-NE SSA 


0OOOC2 


4100 


C450 


00484 


171* 




LA 


O.MSGl 


VARIABLE ADOR 




0 l-MESSA 


OOOOC 6 


5001 


f 008 


0 0008 


172* 




ST 


0.8( 1, 151 


STORE INTO MESSAGE LIST 




01-MESSA 


OOOOCA 


58F2 


0020 


00020 


173* 




L 


15,32i(»2)J 


ADDRESS OF CVT 




02-OPPSU 


OOOOCE 


58FF 


0090 


0 0090 


174* 




L 


I5,li6*28( 15) 


MESSAGE SUPPORT ROUTINE 




02-OPPSU 


000 00 2 


05£F 






175* 




8ALR 


14, 15 


CALL SUPPQi^T ROUTINE 




02-OPPSU 










176 




ENOIF 








00037000 


000004 








177*IF10007 


OS 


OH 






01-ENDI F 










178 * 










» 


00038000 










179 ♦* 


THE FOLLOWING GETARRAY MACRO 


HILL RETRIEVE THE ADDRESS 


** 


00039000 










180 ** 


(TYPE= 


A DOR ) 


OF ARRAY (NAME=) 


OPPZSAMP AND PLACE THE ADDRESS 


** 


00040000 










181 ** 


IN LOCATION 


' ARRAY • (DAT A= ) . 






00041000 










182 * 












00042000 










183 




GETARRAY NAME=0PPZSAMP, 


DATA=ARRAY,TYPE=ADDR,DC VTR=($2) 




00043000 


0000D4 








184* 




CHOP 


0,4 






01-GETAR 


000004 


4510 


COAC 


OOOEO 


185* 




BAL 


l.GAOOll 






01-GETAR 


000008 


C40 7D7E9E2C1D4D7 




186*00011 


DC 


CL8« OPPZSAMP' 






01-GETAR 


0000 60 








187*GA0011 


CNOP 


0,4 






0 l-GETAR 


OOOOE 0 


4100 


C3FC 


00430 


188* 




LA 


0, ARRAY 


ADDRESS OF DATA 




01-GETAR 


0000E4 


58F2 


0020 


00020 


189* 




L 


15,32l{$2)) 


ADDRESS OF CVT 




02-OPPSU 


0OOOE8 


SBFF 


0073 


00078 


190* 




L 


I5,ll6*4( 15» 


GETARRAY SUPPORT ROUTINE 




02-OPPSO 


OOOOEC 


45E0 


code 


000F2 


191* 




BAL 


14,'!'*6 






02-OPPSU 


OOQOFO 


0200 






192* 




DC 


ALl (2» ,AL1 <0) 






02-DPPSU 


0000F2 


BFF8 


EOOO 


00000 


193* 




ICM 


15,8, 0( 14) 


INSERT THE MACRO ID 




02-OPPSU 


000 OF 6 


05EF 






194* 




BALR 


14,15 


CALL SUPPORT ROUTINE 




02-DPPSU 










195 »* 


IF THE 


ARRAY ADDRESS HAS RETRIEVED FROM THE DATA BASE THEN 


** 


00044000 










196 




IF F, 


( *15), IS, ZERO, THEN 






00045000 


0O0OF8 


12FF 






197* 




LTR 


H5,$15 






01-IF 


OOOOFA 


47T0 


C22 8 


0025C 


198* 




BC 


7,!F 10013 






01-If 


OOOOFE 


5830 


C3FC 


00430 


199 




L *3, ARRAY 


PLACE ARRAY ADDRESS IN REG 3 




00046000 










200 


OUTPUT 


MESSAGE 66 , 


WHICH CONTAINS ARRAY<VAR=) 


♦ * 


00047000 










201 ** 


OPPZSAMP, TO 


THE SYSTEM CONSOLE ( ROUTE= I ) 




00048000 










202 




MESSAGE 66tV AR=( ( $3) ) 


,0CVTR=t t2l 




00049000 


000102 


0700 






203* 




CNOP 


0,4 






01-MESSA 


000104 


4510 


COEO 


00U4 


204* 




BAL 


1,HSG0014 






Ol-MESSA 


000108 


01 






205* 




DC 


ALl (0*1 ) 


VARIABLE COUNT 




01-MESSA 


000109 


00 






205* 




DC 


AL 1( 0> 


ROUTING CODE COUNT 




01-MESSA 


000 lOA 


0000 






207* 




DC 


AL2(0) 


MESSAGE NUMBER 




01-MESSA 


OOOIOC 


00 






208* 




DC 


X'OO' 


ACTION CODE 




01-MESSA 


000100 


000000 




209* 




DC 


AL3(0) 


USER RETURN AREA 




01-MESSA 


OOOllO 


00000000 




210* 




DC 


IAL4101 


MESSAGE VARIABLE 




01-MESSA 


000114 








2ll*MSG0014 


DS 


OF 






01-MESSA 


000114 


4100 


0042 


00042 


212* 




LA 


0,66 LOAD MSG # INTO REGISTER 0 




01-MESSA 


000118 


4 00 J 


O0O2 


00002 


213* 




STH 


0,2(1) MOVE MSG 


« TO PARAMETER LIST 




01-MESSA 


OOOllC 


IBFF 






214* 




SR 


15,15 


ZERO REG 15 FOR IC 




01-MESSA 


OOOllE 


43FI 


0001 


00001 


215* 




IC 


15,1( 1» 


# OF ROUTE COOES IN PARAMETER 


LI ST 


01-MESSA 


000122 


89F0 


0001 


00001 


216* 




SLL 


15,1 


LENGTH OF ROUTE CODE IN PARAM 


LIST 


Ol-ME SSA 


000126 


5031 


F008 


00008 


217* 




ST 


$3,8( 1,15) 


STORE VARIABLE INTO PARAMETER 


LIST 


01-MESSA 


000i2A 


58F2 


002 0 


00020 


218* 




L 


15,32((*2)) 


ADDRESS OF CVT 




02-OPPSU 



OPPZSAMP SAMPLE PROGRAM PAGE 6 



LOC 


OBJECT CODE 


AOORl 


ADDR2 


STMT 


SOURCE STATEMENT 




ASM H V 04 09. 15 


11/04/75 


000 12 E 


58FF 


0090 




00090 


219* 




L 


15.116+28(15) 




MESSAGE SUPPORT ROUTINE 




02-DPPSU 


000132 


05EF 








220 + 




BALR 


14, 15 




CALL SUPPORT ROUTINE 




02-DPPSU 












221 * 












* 


00050000 












222 ♦* 


THE 


FOLLOWING PUTLOG MACRO HILL 


LOG OUT ARRAY (NAME=) DPPZSAMP** 


00051000 












223 * 














00052000 












224 




PUTLOG NAME=DPPZS AMP, 


DCVTR=( $2 » 




00053000 


000134 


4510 


ClOC 




00140 


225* 




BAL 


l,*+12 




A (ARRAY NAME! 




Ol-PUTLO 


000138 


C40707E9E2C 10407 




2 26* 




DC 


CL8' DPPZSAMP • 




ARRAY NAME 




01-PUTLO 


000 140 


58F2 


0020 




00020 


227* 




L 


15,32( ($2) ) 




ADDRESS OF CVT 




02-OPPSU 


000144 


58FF 


00B8 




000B8 


228* 




L 


15, ll6+68( 15) 








02-DPPSU 


000148 


4560 


CllA 




0014E 


229+ 




BAL 


14, ♦♦6 








02-DPPSU 


00014C 


0100 








230^ 




OC 


ALl(l) ,AL1(0) 








02-DPPSU 


00014E 


BFF8 


EOOO 




00000 


231* 




ICM 


15,8,0( 14) 




INSERT THE MACRO 10 




02-DPPSU 


000152 


0 5EF 








232* 




BALR 


14,15 




CALL SUPPORT ROUTINE 




02-DPPSU 












233 


IF ARRAY OPPZSAMP WAS LOGGED 


OUT THEN 


* * 


00054000 












234 




IF 


F, ( $15), IS. ZERO, THEN 




00055000 


000 154 


12FF 








2 35+ 




LTR 


tl5,$15 








01- IF 


000156 


4770 


C228 




0025C 


236 + 




BC 


7, IF20018 








01- IF 












237 ** 


OUTPUT MESSAGE 68 




WHICH CONTAINS MSG2(VAR=) TO 




00056000 












238 »* 


THE 


SYSTEM 


CONSOLE (R0UTE=1 ). 








00057000 












239 




MESSAGE 68,VAR=( MSG2) 


,0C VTR= ($2,' 




00058000 


00015A 


0700 








240+ 




CNOP 


0,4 








01-ME SSA 


00015C 


4510 


C138 




00 J6C 


241 + 




BAL 


I ,MSG0019 








01-MESSA 


000 160 


01 








242 + 




OC 


ALKO + l) 




VARIABLE COUNT 




01-MESSA 


000161 


00 








243 + 




OC 


ALl(O) 




ROUT ING CODE COUNT 




01-ME SSA 


000 I 62 


0000 








244 + 




OC 


AL 2( 0) 




MESSAGE NUMBER 




01-MESSA 


000 1 64 


00 








245 + 




OC 


X'OO' 




ACTION CODE 




01-ME SSA 


000165 


000000 






246+ 




OC 


AL3( 0) 




USER RETURN AREA 




01-MESSA 


0 00 168 


00000000 






247 + 




OC 


1AL4<0» 




MESSAGE VARIABLE 




01-MESSA 


000 1 6C 










248+MSG0019 


' OS 


OF 








01-ME SSA 


000 16 C 


4100 


0044 




A A r\ A A 


249 + 




LA 


0,68 LOAD MSG 


# INTO REGISTER 0 




0 1— ME SSA 


000 170 


4001 


0002 




0 0002 


250 + 




STH 


0, 2( 1) MOVE MSG 




TO PARAMETER LIST 




01-ME SSA 


000 1T4 


18FF 








251 + 




SR 


15,15 




ZERO REG 15 FOR IC 




A 1 ^ MP CCA 


000176 


43F1 


0001 




00001 


252 + 




IC 


15, U 1) 




* OF ROUTE COOES IN PARAMETER 


LIST 


01-MESSA 


00017& 


89F0 


0001 




00001 


253 + 




SLL 


15,1 




LENGTH OF ROUTE CODE IN PARAM 


LIST 


01-ME SSA 


000l7f 


4100 


C458 




0048C 


2 54+ 




LA 


0,MSG2 




VARIABLE ADDR 




01-MESSA 


000182 


5001 


F008 




00008 


255 + 




ST 


0,8( 1,15} 




STORE INTO MESSAGE LIST 




01-MESSA 


000186 


5PF2 


0020 




00020 


256 + 




L 


15 ,32( { $2) ) 




ADDRESS OF CVT 




02-DPPSU 


00018A 


58FF 


009 0 




00090 


257 + 




L 


l5,ll6+28( 15J 




MESSAGE SUPPORT ROUTINE 




02-DPPSU 


00018E 


05EF 








258 + 




BALR 


14,15 




CALL SUPPORT ROUTINE 




02-DPPSU 












259 * 












♦ 


00059000 












260 «♦ 


THE 


FOLLOWING GETLOG MACRO WILL 


LOG IN ARRAY{NAME=) DPPZSAMP 




00060000 












261 ♦* 


AND 


PLACt(AREA=J THE ARRAY AT 


LOCATION LOGCOPY . 


* 


00061000 












262 * 












* 


00062000 












263 




GETLOG NAHE=DPPZSAMP, 


AREA=L0GC0PY,0CVTR=(S2) 




00063000 


000190 










264 + 




CNOP 


0,4 








01-GE TLO 


000190 


4510 


C178 




OOIAC 


265+ 




BAL 


1 ,*+28 




BRANCH ARROJNO PARMS 




01-GETLO 


000194 


OOOOOl A4 






266 + 




DC 


AL 1(0),AL3(* + 15) 




ARRAY IDENTIFIER 




01-GETLC 


000198 


00000438 






267 + 




OC 


A( LOGCOPY) 




OUTPUT AREA 




01-GETLO 


00019C 


00000000 






268+ 




OC 


At 0) 




RELATIVE COPY 




01-GETLO 


0001 AO 


00000000 






269 + 




DC 


A(0) 




LOG COPY REFERENCE 




01-GETLO 


0001A4 


C40707E9E2C 10 407 




270+ 




DC 


CL3' DPPZSAMP' 








01-GE TLO 


0001 AC 


58F2 


0020 




00020 


271 + 




L 


15,32( (»2) ) 




AOORESS OF CVT 




02-DPPSU 


OOOIBO 


58FF 


0064 




000B4 


272 + 




L 


15, 1 16+64( 15) 








02-DPPSU 


0001B4 


05EF 








273+ 




BALR 


14,15 




CALL SUPPORT ROUTINE 




02-OPPSU 



a 

w 
o 
t-) 
p- 

r+ 
I-"' 
O 

D 

(1> 

O 
'V 
fO 

»-) 

0> 
r<- 
H- 
O 

3 

» 



LOC OBJECT COOe 



SAMPLE PROGRAM 



AODR 1 AD0R2 STMT SOURCE STATEMENT 



27* ** IF ARRAY DPPZSAMP WAS LOGGED IN THEN 











275 




IF F,( $15 ) , IS.ZERQ.THEN 


000 186 


12FF 






276* 


LTR 


$15, $15 


0001B8 


4770 


C228 


0025C 


277 ♦ 


BC 


7, 1F30023 










278 ** 


OUTPUT MESSAGE 66 .WHICH CONTAINS THE LOGGED IN ♦* 










279 *♦ 


ARRAY! VAR= 


) DPPZSAMP, TO THE SYSTEM CONSOL E ( ROUT E = I ) 


000 IBC 


4140 


C41C 


00450 


280 

281 ** 

282 




LA $4, LOGCOPY+24 LOGGED ARRAY ADORESSCIST 24BYTES OF A 

LOGGED ARRAY CONTAINS A HEADER 
MESSAGE 66,VAR =( { $4 ) ) ,0C VTR= ( $2 ) ,R0UTE = 1 


000 IC 0 








283 + 


CNOP 


0,4 


OOOICO 


4510 


ClAO 


0010 4 


284* 


SAL 


1 .MSG 002 4 


OOOIC* 


01 






285* 


DC 


ALUO + n VARIABLE COUNT 


000 IC 5 


01 






286* 


DC 


ALl(l) ROUTING CODE COUNT 


0001C6 


0000 






287* 


DC 


AL2( 0» MESSAGE NUMBER 


000 IC 8 


00 






288* 


DC 


X'OO' ACTION CODE 


0001C9 


000000 




289* 


DC 


AL3(0) USER RETURN AREA 


OOOICC 


0000 






290 + 


DC 


AL 2( 0) ROUTING CODE 


OOOICE 


00000000 




291 + 


DC 


1AL4(0) MESSAGE VARIABLE 


000104 








292+MSG0024 OS 


OF 


OOOID* 


4100 


0042 


00042 


293 + 


LA 


0,66 LOAD MSG # INTO REGISTER 0 


000108 


4001 


0002 


00002 


294 + 


STH 


0,2(1) MOVE MSG # TO PARAMETER LIST 


000 1 DC 


4100 


0001 


00001 


295 + 


LA 


0,1 LOAD ROUTING CODE INTO REGISTER 0 


OOOIEO 


4001 


0008 


00008 


296 + 


STH 


0,8(1) STORE ROUTING CODE INTO PARAMETER LIST 


OOOIE* 


9680 


1008 


00008 


297 + 


01 


a(l),X'80' SET HIGH BIT OF LAST ROUTINE CODE 


000 IE8 


IBFF 






298 + 


SR 


15,15 ZERO REG 15 FOR IC 


000 IE A 


43F1 


0001 


00001 


299+ 


!C 


15,1(1) « OF ROUTE CODES IN PARAMETER LIST 


OOOIEE 


89F0 


0001 


00001 


300+ 


SLL 


15,1 LENGTH OF ROUTE CODE IN PARAM LIST 


000IF2 


5041 


F008 


00008 


301 + 


ST 


$4,8(1,15) STORE VARIABLE INTO PARAMETER LIST 


0001F6 


58F2 


002 0 


00020 


302 + 


L 


15,32(($2)) ADDRESS OF CVT 


0001 FA 


58FF 


0090 


00090 


303 + 


L 


15,116+28(15) MESSAGE SUPPORT ROUTINE 


OOOIFE 


05EF 






304 + 

305 * 


BALR 


14,15 CALL SUPPORT ROUTINE 

* 



306 THE FOLLOWING PUTARRAY MACRO WILL PLACE(DATA=) THE 

307 *♦ LOGGED IN ARRAY(NAME=) DPPZSAMP IN THE DATA BASE . 

308 * 

309 PUTARRAY NAME = DPP Z SAMP ,DA TA = ( $4) ,DC VTR= ( $2 ) 



000200 






310 + 


CNOP 


0,4 




000200 


4510 C1D8 


0020C 


311 + 


SAL 


l,PA0026 




000204 


C40707E9E2C104D7 




312+A0026 


DC 


CL8«DPPZSAMP« 


ARRAY NAME 


00020C 






313+PA0026 


CNOP 


0,4 




00020C 


1804 




314+ 


LR 


0,S4 


ADDRESS OF DATA 


00020E 


58F2 0020 


00020 


315 + 


L 


15,32( ( $2)1 


ADDRESS OF CVT 


000212 


58FF 007C 


0007C 


316+ 


L 


15,116+8(15) 


PUTARRAY SUPPORT ROUTINE 


000216 


45E0 C1E8 


0021C 


317 + 


BAL 


l4,*+6 




00021A 


7000 




318 + 


DC 


AL 1( 112),AL1(0) 




00021C 


BFF8 EOOO 


00000 


319+ 


ICM 


15,8,0H4) 


INSERT THE MACRO ID 


000220 


05EF 




320 + 


BALR 


14, 15 


CALL SUPPORT ROUTINE 








321 *♦ IF 


THE LOGGED ARRAY HAS PLACED 


IN THE DATA BASE THEN 








322 




IF F,(*15) , IS, ZERO, 


,THEN 


000222 


12FF 




323 + 


LTR 


$15,$15 




000224 


4770 C228 


0025C 


324+ 


BC 


7,IF40028 





000228 



325 *• OUTPUT MESSAGE 68, WHICH CONTAINS MSG3(VAR=), TO THE 

326 *♦ SYSTEM CONSOL E (ROUT E= 1 ) 

327 MESSAGE 68 , VAR= { MSG3 ) ,DCVTR= ( $2 ) 
328+ CNOP 0,4 



ASM H V 04 09.15 11/04/75 



00064000 

00065000 

01- IF 

01-IF 

00066000 

00067000 

00068000 

00068100 

00068200 

01-ME SSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

Ol-ME SSA 

01-MESSA 

01-MESSA 

01-MESSA 

01- MESSA 

02- OPPSU 
02-OPPSU 
02-DPPSU 
00069000 
00070000 
00071000 
00072 000 
00073000 
Ol-PUTAR 
Ol-PUTAR 
Ol-PUTAR 
Ol-PUTAR 

01- PUTAR 

02- DPPSU 
02-DPPSU 
02-DPPSU 
02-DPPSU 
02-DPPSU 
02-DPPSU 
00074000 
00075000 
Ol-IF 
01-IF 
00076000 
00077000 
00078000 
01-MESSA 



SAHPLE PROGRAM 



LOC 


OBJECT COOE 


ADORl A DOR 2 


STMT SOURCE 


STATEMENT ASM H V 0* 09.15 


ll/0*/75 


000228 


*510 


C20* 


00238 


329 + 


BAL 


1,MSG0029 


01-MESSA 


00022C 


01 






330* 


DC 


ALllO+1) VARIABLE COUNT 


Ol-MESSA 


000220 


00 






331 ♦ 


DC 


ALKO) ROUTING CODE COUNT 


01-MESSA 


0002 2f 


0000 






332* 


DC 


AL2tO) MESSAGE NUMBER 


01-MESSA 


000230 


00 






333 + 


DC 


X'00« ACTION CODE 


Ol-MESSA 


000231 


000000 




33**^ 


DC 


AL3(0) USER RETURN AREA 


Ol-MESSA 


00023* 


oooooooo 




335* 


DC 


IAL*(0J MESSAGE VARIABLE 


01-MESSA 


000238 








336+MSG0029 


OS 


OF 


Ol-MESSA 


000238 


*100 


00** 


000** 


337* 


LA 


0,68 LOAD MSG # INTO REGISTER 0 


01-MESSA 


00023C 


*001 


0002 


C0002 


338* 


STH 


0,2(1) MOVE MSG # TO PARAMETER LIST 


Ol-MESSA 


0002*0 


IBFF 






339* 


SR 


15,15 ZERO REG 15 FOR IC 


01-MESSA 


0002*2 


*3Fl 


0001 


00001 


3*0* 


IC 


15,1 m * OF ROUTE COOES IN PARAMETER LIST 


01-MESSA 


0002*6 


89F0 


0001 


OOOOl 


3*U 


SLL 


15,1 LENGTH OF ROUTE CODE IN PARAM LIST 


Ol-MESSA 


0002*A 


*100 


C*6 0 


00*9* 


3*2* 


LA 


o,msg:; variable ador 


Ol-MESSA 


0002*6 


5001 


F008 


00008 


3*3+ 


ST 


0,8(1,15) STORE INTO MESSAGE LIST 


01-MESSA 


000252 


58F2 


0020 


00020 


3*** 


L 


15,321(42)) ADDRESS OF CVT 


02-DPPSU 


000256 


58FF 


0090 


00090 


3*5+ 


L 


15,116+26(15) MESSAGE SUPPORT ROUTINE 


02-0PPSU 


00025A 


05EF 






3*6* 


BALR 


1*,15 CALL SUPPORT ROUTINE 


02-DPPSU 










3*7 






00079000 


00025C 








3*8+1 F*0028 


OS 


OH 


01-ENOIF 










3*9 


ENDJF 


00080000 


00025C 








350+IF30023 


OS 


OH 


Ol-ENOIF 










351 


ENOIF 


0OC81OO0 


00025C 








352*IF200ie 


OS 


OH 


Ol-ENDIF 










353 


ENDIF 




00082000 


00025C 








35*+IF 10013 


OS 


OH 


01- ENOIF 










355 * 




♦ 


00083000 










356 »* THE FOLLOWING GEilTEM KACRO WILL RETRIEVE THE CONTENTS * 


0008*000 










357 •* ( TYPE 


= DATA i 


OF ITtM{NAME = ) DPPSAMP2 AND PLACE(OATA=) THE OATA*^ 


00085000 










356 *• AT LOCATION 


'ITEM'. «« 


00086000 










359 ♦ 




♦ 


00087000 










360 


GET I TEH NAME=DPPSAMP2»DATA=I TE«,TVPE=DATA,DCVTR=($2J 


00088000 


00025C 








361* 


CNOP 


0,* 


01-GETI I 


00025C 


*510 


C2J8 


0026C 


362* 


BAL 


l,GI0035 


Ol-GEI IT 


000260 


C*D707E2C10*D7F2 


363*10035 


DC 


CL8»0PPSAMF2» ITEM NAME 


01-GETIT 


000268 


00000* 7e 




36** 


DC 


Atl(0!,AL3(neMi 


Ol-GeilT 


00026C 








365*010035 


CNOP 


0,* 


Ol-GETir 


00026C 


5800 


C23* 


00268 


366 + 


L 


0,10035*8 ADDRESS OF OAT* 


01~GETIT 


000270 


58F2 


0020 


00020 


367* 


L 


15,32({i2)) ADDRESS OF CVT 


02-DPPSU 


00027* 


58FF 


0080 


00080 


368 + 


L 


15,116*12(15) GETITEM SUPPORT ROUTINE 


02-OPPSU 


000278 


*5E0 


C2*A 


0027E 


369+ 


BAL 


1*,^*6 


02-DPPSU 


00027C 


7800 






370+ 


DC 


AL1(120) .ALKO) 


02-DPPSU 


00027E 


BFF8 


EOOO 


00000 


371 + 


ICM 


15,8,0(1*) INSERT THE MACRO ID 


02-OPPSU 


000282 


05EF 






372 + 


BALR 


l*,i5 CALL SUPPORT ROUTINE 


02-DPPSU 










373 IF ITEM DPPSAMP2 WAS RETRIEVED THEN ** 


00089000 










37* 


IF F, 


($15), IS, ZERO, THEN 


00090000 


00028* 


12FF 






375+ 


LTR 


*l5,tl5 


01-IF 


000286 


*770 


C310 


003** 


376 + 


BC 


7, IF 10037 


01- IF 










377 ♦♦OUTPUT 


MESSAGE 69, WHICH CONTAINS tVAR=) THE ITEM, TO THE ♦♦ 


00091000 










378 ♦♦ SYSTEM CONSOLE (R0UTE=1 > ♦♦ 


00092000 










379 


MESSAGE 69,VAR={ ITEM ) ,0C VTR ={ * 2J ,R0UTE=1 


00093000 


00028A 


0700 






380+ 


CNOP 


0,* 


01-MESSA 


00028C 


*510 


C26C 


002A0 


381 + 


BAL 


1 ,MSG0038 


01-MESSA 


000290 


01 






382 + 


DC 


AL1(0*1) VARIABLE COUNT 


01-MESSA 


000291 


01 






383 + 


DC 


ALKH ROUTING CODE COUNT 


01-MESSA 



DPPZSAMP 
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LOC 


OBJECT COOE ADDRl 


AD0R2 


STMT 


SOURCE 


STATEMENT ASM H V 04 09.15 


11/04/75 


000?92 


0000 






384* 




DC 


AL2(0) MESSAGE NUMBER 




Ol-MESSA 


00029-^ 


00 






385* 




DC 


X '00 • AC TION COOE 




01-MESSA 


000295 


000000 




386+ 




DC 


AL3(0I USEk RETURN AREA 




Ol-ME SSA 


000298 


0000 






387 + 




OC 


AL2(0> ROUTING CODE 




01-M£SSA 


00029A 


00000000 




3S9«- 




DC 


1AL4(0J MESSAGE VARIABLE 




Ol-ME SSA 


0002 AO 








389*MSG0038 


0 S 


OF 




Ol-MESSA 


0002A0 


4100 


0045 


00045 


390 + 




LA 


0,69 LOAD MSG » INTO REGISTER 0 




Ol-MESSA 


0002A4 


4001 


0002 


00002 


39U 




STH 


0,2(H MOVE MSG M TO PARAMETER LIST 




Ol-ME SSA 


0002 A8 


4100 


000 1 


00001 


392 + 




LA 


0,1 LOAD ROUTING CODE INTO REGISTER 0 




Ol-MESSA 


0002AC 


4001 


000 8 


00008 


393* 




STH 


0,8(1» STORE ROUTING CODE INTO PARAMETER LIST 




Ol-ME SSA 


000260 


9680 


1008 00008 




394* 




01 


8il),X'80' SET HIGH BIT OF LAST ROUTINE 


COOE 


Ol-ME SSA 


000?B4 


IBFF 






395 + 




SR 


15,15 ZERO REG 15 FOR IC 




Ol-MfcSSA 


0002B6 


43F1 


0001 


00001 


396* 




IC 


15,1(1) # OF ROUTE CODES IN PARAMETER 


LI SI 


Ol-ME SSA 


0002RA 


89F0 


0001 


00001 


397* 




SLL 


15,1 LENGTH OF RfJUT E CODE IN PARAM 


LIST 


Ol-ME SSA 


O0026F 


4100 


C44 A 


0 047E 


398 + 




LA 


0, ITEM VARIABLE ADOR 




Ol-MESSA 


0002C2 


5001 


F OOfi 


00008 


399 + 




ST 


0,8(1,15) STORE INTO MESSAGE LIST 




Ol-MESSA 


0002C6 


58F2 


0020 


00020 


400t 




L 


15 ,32( ( $2) ) ADDRESS OF CVf 




02-OPPSU 


0002CA 


58FF 


0090 


00090 


401 ♦ 




L 


15,116+28(15) MESSAGE SUPPORT ROUTINE 




02-DPPSU 


0002CF 


0 5EF 






402* 




BALR 


14,15 CALL SUPPORT ROUTINE 




02-OPPSU 










403 * 








* 


00094000 










404 ♦* 


THE FLLOWING PUT !T EM MACRO WILL PLACE(OATA=) THE RETRIEVED 


** 


00095000 










405 *♦ 


I TEH( NAME= 


) DPPSAMP2 IN THE DATA BASE . 


** 


00096000 










406 * 










00097000 










407 




PUT IT EM NAME=0PPSAMP2, 0ATA=!TEM,0C VTR= { $2) 




00098000 


000200 








408+ 




CNOP 


0,4 




Ol-PUTIT 


000200 


4510 


c2Ar. 


002E0 


409 + 




BAL 


I, P 10040 




01-PUTIT 


000204 


C4D7D7E2C 10 40 7F2 




410+P0040 


DC 


CL8« DPPSAMP2* ITEM NAME 




Ol-PUTl T 


00020C 


000004 7E 




411 + 




DC 


AL 1(0) ,AL3( ITEM) 




Ol-PUTIT 


0002E0 








412+P 10040 


CNOP 


0,4 




Ol-PUTIT 


0Q02E0 


5800 


C ?A8 


0020C 


413 + 




L 


0,P0040+8 ADOPESS OF DATA 




Ol-PUTl T 


0002 64 


58F2 


0020 


00020 


414 + 




L 


15,32( ($2) ) ADDRESS OF CVT 




02-DPPSU 


0002E fi 


58FF 


0084 


00084 


415 + 




L 


15,116+16(15) PUTITEM SUPPORT ROUTINE 




02-OPPSU 


000260 


45E0 


C2BE 


002F2 


416+ 




BAL 


14, ♦♦6 




02-DPPSU 


0002F0 


A800 






417 + 




DC 


AL U 168),AL1( 0) 




02-DPPSU 


0002F2 


BFF8 


E 000 


00000 


418 + 




ICM 


15,8,0(14) INSERT THE MACRO ID 




02-OPPSU 


0002 Ffc 


05EF 






419+ 




BALR 


14,15 CALL SUPPORT ROUTINE 




02-DPPSU 










420 ** 


IF ITEM 0PPSAMP2 WAS UPDATED THEN 


** 


00099000 










421 




IF 


F, ($15), IS, ZERO, THEN 




OOlOOOOO 


0002F8 


12FF 






422 + 




LTR 


»15,$ 15 




Ol-IF 


000 2F A 


4770 


C310 


00344 


423 + 




BC 


7, IF20042 




Ol-IF 










424 ♦♦OUTPLfT 


MESSAGE 68, WHICH CONTAINS MSG4(VAR=> ,T0 THE SYSTEM 




OOlOlOOO 










425 ** 


CONSOLE tROUTE=U . 




00102000 










4 26 




MESSAGE 68»VAR=(MSG4),DCVTR=($2» ,R0UTE=1 




00103000 


0002FE 


0700 






42 7+ 




CNOP 


0,4 




Ol-MESSA 


000300 


4510 


C2E0 


00314 


428 + 




BAL 


1,MSG0043 




Ol-MESSA 


000304 


01 






429+ 




OC 


AH(0 + n VARIABLE COUNT 




Ol-MESSA 


000305 


01 






430 + 




DC 


ALl(l) ROUTING COOE COUNT 




Ol-MESSA 


000306 


0000 






431 + 




DC 


AL2(0) MESSAGE NUMBER 




Ol-MESSA 


000308 


00 






432 + 




OC 


X'OO* ACTION COOE 




Ol-MESSA 


000 30 9 


000000 




433 + 




DC 


AL3(0) USER RETURN AREA 




Ol-MESSA 


000 30C 


0000 






434 + 




OC 


AL2(0 ) ROUT ING COOE 




Ol-MESSA 


00030E 


00000000 




435+ 




OC 


1AL4(0) MESSAGE VARIABLE 




Ol-MESSA 


000314 








436 + MS G0043 


OS 


OF 




Ol-MESSA 


000314 


4100 


0044 


00044 


437+ 




LA 


0,68 LOAD MSG « INTO REGISTER 0 




Ol-MESSA 


000318 


4001 


0002 


00002 


438 + 




STH 


0,2(1) MOVE MSG # TO PARAMETER LIST 




Ol-MESSA 



OPPZSAMP 



SAMPLF f>ROGRAM 



PAGE 10 



LOC 


OBJECT CODE 


AODRl 


A DDR 2 


STMT SOURCE 


STATEMENT 


ASM H V 04 09. 


00031C 


4100 


0001 




00001 


439 + 


LA 


0, 1 LOAD ROUT ING 


CODE INTO REGISTER 0 


000320 


4001 


0008 




00006 


440* 


STH 


OtSd) STORE ROUTING CODE INTO PARAMETER LIST 


000324 


9680 


1008 


00008 




441 + 


01 


8( I) ,X' 80* 


SET HIGH SIT OF LAST ROUTINE CODE 


000328 


IBFF 








442 + 


SR 


15,15 


ZERO REG 15 FDR IC 


00032A 


43FI 


0001 




0000 I 


443+ 


IC 


15,1(1) 


* OF ROUTE CODES IN PARAMETER LIST 


00032E 


89F0 


0001 




00001 


444 + 


SLL 


15,1 


LENGTH OF ROUTE CODE IN PARAM LIST 


000332 


4100 


C468 




004 9C 


445 + 


LA 


0,MSG4 


VARIABLE AOOR 


000336 


5001 


F008 




00008 


446+ 


ST 


0,8( 1,15) 


STORE INTO MESSAGE LIST 


0003 3A 


58F2 


0020 




00020 


447 + 


L 


15,32( <(2) ) 


ADDRESS OF CVT 


00033E 


58FF 


0090 




00090 


448+ 


L 


15,116+28(15) 


MESSAGE SUPPORT ROUTINE 


000342 


05FF 








449 + 


BALR 


14, 15 


CALL SUPPORT ROUTINE 












450 


ENDIF 




000344 










451+IF20042 


OS 


OH 














452 


END IF 






000344 










453+IF10037 


DS 


OH 





454 * 

455 THE FOILOWING PTIME MACRO WILL CREATE A PTOE(ADD) 

456 *♦ CAUSE DPPSAMPl ( TASK* AND E P= ) TO BE PAICHEO THREE 

457 (COUNT=) WITH A I S£COND( START =) INTERVAL BETWEEN 



WHICH WILL *» 
TIMES ** 
EACH PATCH** 









458 * 






* 








4 59 


PTIME 


A0D,START=(REL,1S ), 
TASK=DPPSAMPl 


,C0UNT = 3,0CVTR=( »2 ) , EP = OPP SAMP 1, 


000344 


4110 C318 


0034C 


460+ 


LA 


X, IHB004 8 


SET UP PARAM LIST ADDRESS 


000348 


47F0 C344 


00378 


46i + 


B 


IH80048A 


BRANCH AROUND LIST 


00034C 






462+IH60048 


DS 


OF 




000 3 4C 


C4D7D7F2C 1D4D7F I 




463 + 


OC 


CLB'DP PSAHPl* 


TASK NAME 


000354 


C4 07 D7 F2CIP4D7F1 




464 + 


DC 


CL8'DPPSAMP1» 


ENTRY POINT NAME 


00035C 


40404040404 04040 




465 + 


OC 


CL8' • 


PRTY REFERENCE NAME 


000364 


00 




466 + 


DC 


ALl to ) 


FLAG BYTE 


000365 


01 




467 + 


DC 


AL U 1) 


QUEUE LENGTH 


000366 


0000 




463 + 


DC 


H'O" 


PRTY RELATIVE VALUE 


000368 


00000000 




469+ 


OC 


A( 0) 


ECB ADDRESS 


00036C 


oooooooooooooooo 




470 + 


OC 


2F'0« 


FREE LENGTH, FREE ADDRESS 


000374 


00000000 




471 + 


OC 


A(Oi 


TC6X 






00378 


472+ IH8004 8A 


EQU 


* 




000378 


41F0 C34C 


00380 


473 + 


LA 


15, IHP0048 


SET UP LI ST ADDRESS 


00037C 






474 + 


CNOP 


0,4 




00037C 


4500 C350 


00384 


475 + 


BAL 


0, IHP0048A 


SET UP REG 0 WITH PARAM LIST 






00380 


476+IHP0048 


EOU 


* 




000380 


0004 




47 7+ 


DC 


AL2(IHP0048A-IHP0048) LENGTH OF PARAMS 


000382 


0000 




478 + 


DC 


AL2(0) 


ID 






00384 


479+IHP0048A 


EQU 


* 




000384 






480+ 


CNOP 


0,4 




000384 


5010 C36C 


003AO 


481 + 


ST 


1, *+12+16 


SAVE PATCH SUPERVISOR LIST ADDRESS 


000388 


5000 C 370 


003A4 


482 + 


ST 


0 , ♦♦16 + 12 


SAVE PATCH PROBLEM LIST ADDRESS 


00038C 


4100 0004 


00004 


483 + 


LA 


0,4 


REQUEST TYPE 


000390 


4510 C378 


003 AC 


484 + 


BAL 


1, PTC047N0 


BRANCH AROUND PTIME PARAMETERS 


000394 


01000064 




485+ 


DC 


ALl ( 1 ) , AL3 ( 100 ) 


START TIME 


000398 


00000000 




486 + 


DC 


AL 1(0),AL3(0) 


INTERVAL TIME 


00039C 


08000003 




487 + 


DC 


ALl (8),AL3(3) 


STOP TIME 


0003A0 


00000000 




488+ 


DC 


A( 0) 


PATCH SUPERV ISOR L 1ST 


0003A4 


00000000 




489 + 


DC 


A(0) 


PATCH PROBLEM PARAMETER LIST 


0003A8 


40404040 




490+ 


DC 


CL4' 


PTOE ID 


0003AC 






491+PT004 7ND 




OS OH 




0003AC 


18F2 




492 + 


LR 


15, ( S2) 


CVT ADDRESS 



01-MESSA 
01-HESSA 
01-MESSA 
01-MESSA 
01-MESSA 
Ol-MESSA 
01-ME SSA 

01- MESSA 

02- DPPSU 
02-DPPSU 
02-OPPSU 
00104000 
01-ENDIF 
00105000 

01- ENDlF 
00106000 
00107000 
00108000 
00109000 
00110000 

XOOIUOOO 
00112000 

02- PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
02-PATCH 
01-PTIME 
01-PTIME 
01-P TIME 
01-PTIME 
01-PTIME 
01-PTIME 
01-PT IME 
01-PTIME 
Ot-PTIME 
01-PTIME 
01-PTIME 

01- PTIME 

02- OPPS.V 



SAMPLE PROGRAM 



PAGE 



a 
a 
w 
o 
n 

r>- 
H- 

o 

£3 

a 

o 
►a 

(D 
M 
Q> 
ft 
H- 
O 

a 

a: 
P) 

3 
C 

0) 



LOC OBJECT CODE 

0003AE BFF8 C381 
0003B2 '♦TOO OOO't 
000366 440F 0008 



0003BA 59F0 C 3E A 
0003BE 47B0 dm 



ADDPl A0DR2 STMT SOURCE STATEMENT 



ASM H V O't 09.15 11/04/75 



003B5 
00004 
00008 



00428 
00408 



49 3* 
494+ 
49 5,< 



ICM 

NOP 
EX 



15, 8, ♦♦T 

04 

0,8< 15) 



10 IN HIGH ORDER BYTE OF REG 
CONSTANT FOR ID 
EXECUTE SVC FROM CVT 











502 


MES! 


000X2 


0700 






503* 


CNOP 


0003C4 


45 10 


C3A4 


00308 


504«- 


BAL 


0003C8 


01 






505* 


DC 


0003C9 


01 






506+ 


OC 


0003CA 


0000 






507 + 


OC 


0003CC 


00 






508* 


DC 


0003CD 


000000 




509+ 


DC 


000300 


0000 






510 + 


DC 


000 30 2 


00000000 




511 + 


DC 


0003D8 








512+MSG0051 


OS 


000308 


4100 


0044 


00044 


513 + 


LA 


000 30C 


4001 


0002 


00002 


514 + 


STH 


0003E0 


4100 


0001 


00001 


515 + 


LA 


0003E4 


4001 


0008 


00008 


516 + 


STH 


0003E8 


9680 


1008 


00008 


517 + 


01 


0003EC 


IBFF 






518 + 


SR 


000 3EE 


43F1 


0001 


OOOOl 


519+ 


IC 


0003F2 


89F0 


0001 


00001 


520+ 


SLL 


0003F6 


4100 


C470 


004A4 


521 + 


LA 


0003FA 


5001 


F 008 


0 0008 


522 + 


ST 


0003FE 


58F2 


0020 


000 20 


523 + 


L 


000402 


58FF 


0090 


0 0090 


524 + 


L 


000406 


05EF 






525+ 
5 26 


BALR 
ENDIF 


000408 








527+IF10050 
528 • 


OS 



496 ** IF RETURN CODE FROM TIME HANGEMENT IS LESS THAN EIGHT THEN 

497 IF F, ($151, LT, EIGHT, THEN 
498+ C »15, EIGHT 

499+ BC 11,IF10050 

500 *♦ OUTPUT MESSAGE 68, WHICH CONTAINS MSG5(VAR=), TO THE SYSTEM 

501 »♦ CONSOLE (ROUTE=ll 
AGE 68,VAR = ( MSGS) ,DC VTR=( $2) ,R0UTE = 1 

0. 4 

1 , MSG0051 



AL 1( 0 + 1 ) 
ALl (1 ) 
AL2( 0) 
X'OO' 
AL3(0) 
AL2(0) 
lAL4t0» 
OF 

0,68 
0.2(1) 



VARIABLE COUNT 
ROUT ING CODE COUNT 

MESSAGE NUMBER 
ACTION CODE 
USER RETURN AREA 
ROUTING CODE 

MESSAGE VARIABLE 



LOAD MSG « INTO REGISTER 0 
MOVE MSG # TO PARAMETER LIST 
0,1 LOAD ROUTING CODE INTO REGISTER 0 
0,8(1) STORE ROUTING CODE INTO PARAMETER LIST 



811) ,X'80' 

15,15 

15,1(1) 

15,1 

0,MSG5 

0,8(1,15) 

I5,32((S2)) 

15,116+281 15) 

14,15 

OH 



SET HIGH BIT OF LAST ROUTINE CODE 
ZERO REG 15 FOR IC 

# OF ROUTE COOES IN PARAMETER LIST 

LENGTH OP ROUTE CODE IN PARAM LIST 

VARIABLE AOOR 

STORE INTO MESSAGE LIST 
ADDRESS OF CVT 

MESSAGE SUPPORT ROUTINE 
CALL SUPPORT ROUTINE 



529 ** THE EXIT MACRO HILL RESTORE ALL REGISTERS AS THEY WERE WHEN ♦* 

530 *♦ DPPZSAHP WAS ENTERED ANO RETURN BACK TO THE SYSTEM. 



02-0PPSV 

02-OPPSV 

02-DPPSV 

00113000 

00114000 

01-IF 

01- IF 

00115000 

00116000 

00117000 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-ME SSA 

01-MESSA 

01-MESSA 

01-MESSA 

01-MESSA 

01- MESSA 

02- DPPSU 
02-DPPSU 
02-DPPSU 
00118000 
01-ENOIF 
00119000 
00120000 
00121000 











531 * 








• 


00122000 










532 


EXIT 


COOE=0 






00123000 


000408 








533+ 


OS 


OH 






Ol-EXIT 


000408 


1810 






534+ 


LR 


1,13 . 


SUB POOL ADDRESS 




01-EXIT 


00040A 


5 800 


0004 


00004 


535 + 


L 


13.4(13) . 


GET CALLER'S SAVE AREA 




Ol-EXIT 


00040E 


5800 


COOO 


00034 


536+ 
537+* 


L 

FREEMAIN 


O.TKGOOOIG 
R.LV=(0) .A=( 1) 


LOAD SP AND LV PARAMETERS 




01-EXIT 


000412 


4111 


0000 


00000 


538 + 


LA 


1,0(1,0) 


CLEAR THE HIGH ORDER 


BYTE XM4571 


02-FREEM 


000416 


OAOA 






5 39 + 


SVC 


10 


ISSUE FREEMAIN SVC 


P2504 


02-FREEM 


00 04 1 8 


98EC 


DOOC 


OOOOC 


540 + 


LM 


14, 12, 12( 131 


RESTORE THE 


REGISTERS 


02-RETUR 


00041C 


92FF 


DOOC 


OOOOC 


541 + 


MVI 


12 (13) ,X»FF' 


SET RETURN 


INDICATION 


02-RETUR 


000420 


41F0 


0000 


00000 


542+ 


LA 


15,0(0,0) 


LOAD RETURN 


CODE 


02-RETUR 


000424 


07FE 






543 + 

544 * 


6R 


14 


RETURN 


♦ 


02-RETUR 
00124000 










545 ** 


SRTOS SAMPLE 


PROGRAM DATA 


ANO CONSTANT AREA 


** 


00125000 










546 ♦ 








m 


00126000 


000426 


0000 



















OPPZSAMP 



«;ample program 
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LOC OBJECT CODE 



AOORl A00R2 STHT SOURCE STATEMENT 



ASM H V 0* 09.15 11/0^/75 



OOO'fZS 00000008 

000430 

000438 

00047E 



000484 07CIE3C3C8404040 
00048C 07E4E3D3O6C74040 
000494 D7E4E3CID909C1E8 
00049C 07E4E3C9EK50 440 
0004 A4 07 E3C9 04 C5 404040 



547 EIGHT 

548 ARRAY 

549 LOGCOPV 

550 ITEM 

551 * 

552 ** 

553 * 

554 MSGl 

555 HSG2 

556 MSG3 

557 MSG4 
556 HSG5 



DC 
OS 
OS 
OS 



F 'S* 

D 

CL70 
CL6 



CONSTANT OF 8 USED IN IF INSTRUCTION 00126100 



ADDRESS OF ARRAY OPPZSAMP 
LOGGED COPY OF ARRAY OPPZSAMP 
CONTENTS OF ITEM DPPSAMP2 



SAMPLE PROGRAM DIAGNOSTIC MESSAGES VARIABLES 



DC 
DC 
DC 
DC 
DC 
END 



CL8* PATCH* 
CLB'PUTLOG* 
CL8«PUTARRAY' 
CL8' PUT ITEM' 
CLS'PTIME" 



PATCH MACRO OIAC^OSTIC MESSAGE 
PUTLOG MACRO DIAGNOSTIC MESSAGE 
PUTARRAY MACRO DIAGNOSTIC ttSSAGE 
PUTITEM MACRO DIAGNOSTIC MESSAGE 
PTIME MACRO DIACNOSITC MESSAGE 



00127000 
00128000 
00129000 
00130000 
00131000 
00132000 
00133000 
00134000 
00135000 
00136000 
00137000 
00138000 



POS .10 


REL. ID 


FL AGS 


ADDRESS 


0001 


0001 


08 


000195 


0001 


0001 


OC 


000198 


0001 


0001 


08 


000269 


0001 


0001 


08 


0002DD 



RELOCATION DICTIONARY 
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ASM H V 04 09.15 11/04/75 



CROSS REFERENCE 



O 
W 

o 

rt- 
H- 
O 
0 



o 

M 

a> 
o 

3 

3 

3 
C 
0> 



SVMBnt 


LEN 


VALUE 


OEFN 


REFERENCES 


)1 


0000 1 


00000001 


0058 


0113 




$15 


0000 1 


OOOOOOOF 


0072 


0148 


0148 


$ 2 


00001 


00000002 


0059 


0113 


0142 










0492 


0523 


$3 


0000 1 


00000003 


0060 


0199 


0217 




0000 1 


00000004 


006 I 


0 280 


0301 


ARRAY 


00008 


000430 


0546 


0188 


0199 


DPPZS A MP 


0000 1 


00000000 


0054 


0096 




E IGHT 


00004 


000428 


0547 


049 8 




GAOO 1 1 


0000 1 


OOOOEO 


0187 


0185 




G 1003 5 


0000 1 


00026C 


0 365 


0362 




IF 10007 


00002 


000004 


0177 


0149 




I FIDO 1 3 


00002 


00025C 


0354 


0198 




I F 1 003 7 


00002 


000344 


0453 


0376 




I F 10050 


00002 


000408 


0527 


0499 




IF 200 1 8 


00002 


00025C 


0352 


0236 




I F20042 


00002 


000344 


045 1 


0423 




IF 30023 


00002 


00025C 


0350 


0277 




IF40028 


00002 


00025C 


0348 


0324 




IHB0005 


00004 


000044 


0124 


0122 




I HB0005A 


00001 


00000070 


01 34 


0123 




IHB0048 


00004 


00034C 


0462 


046 0 




I HB0048A 


OOOOl 


00000378 


0472 


046 1 




I HP0005 


00001 


00000078 


0138 


0135 


0139 


I HP0005A 


00001 


0000007C 


0141 


0137 


0139 


I HP 004 8 


OOOOl 


00000330 


0476 


0473 


0477 


I HP 0048A 


0000 1 


00000384 


0 479 


0475 


0477 


ITEM 


00006 


00047E 


0550 


0 364 


0398 


I 0035 


00 00 8 


000260 


0363 


0366 




LOGCOPY 


00070 


000438 


0549 


0267 


0280 


MSG0008 


00004 


0000A4 


0 162 


0154 




MSG00I4 


00004 


0001 14 


0211 


0204 




MSGOOl 9 


00004 


000 16C 


0248 


0241 




MSG0024 


00004 


0001 04 


0 292 


0284 




MSG0029 


00004 


000238 


0336 


0329 




MS GOO 3 8 


00004 


0002A0 


0389 


0381 




HSG0043 


00004 


000314 


0436 


0428 




NSG0051 


00004 


0003D8 


0512 


0504 




MSGl 


00008 


000484 


0554 


0171 




MSG2 


00008 


00048C 


0555 


0254 




MSG3 


00008 


000494 


0556 


0 342 




MSG4 


00008 


00049C 


0557 


0445 




MSGS 


00008 


0004A4 


0558 


0521 




PA0026 


OOOOl 


00020C 


0313 


0311 




PI0040 


OOOOl 


0002E0 


0412 


0409 




PT0047ND 


0000 2 


0003AC 


0491 


0484 




P0040 


00008 


0002D4 


0410 


0413 




TKGOOOIG 


OOOOl 


000034 


0102 


0084 


0536 


TKGOOOIM 


00004 


000034 


0101 


0104 




WORK 


OOOOl 


00000000 


0094 


0097 





ASM H V 04 09.15 11/04/75 



0197 
0173 



0314 



0197 
0189 



0235 
0218 



0235 
0227 



0276 
0256 



0276 
0271 



0323 
0302 



0323 
0315 



0375 
0344 



0375 
0367 



0422 
0400 



0422 
0414 



0498 
0447 



0411 



DIAGNOSTIC CROSS REFERENCE AND ASSEMBLER SUMMARY 
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ASH H V 04 09.15 11/04/75 

NO STATEMENTS FLAGGED IN THIS ASSEMBLY 

OVERRIDING PARAMETERS- NO DECK ,NOL OAD , XREF ( SHORT I 
OPTIONS FOP THIS ASSEMBLY 

NODECK, NOOBJECT, LIST, XREF{ SHORT), NORE NT , NOTEST, NOBATCH, ALIGN, ESQ, RLO, L I NE COUNT ( 55 ) , FLAG(O), SYSPARMI) 
NO OVERRIDING DO NAMES 



165 CARDS FROM SYSTN 4267 CARDS FRCM SYSLIB 

654 LINES OUTPUT 0 CARDS OUTPUT 



EXTERNAL SYMBOL DICTIONARY 



SYMBOL TYPF ID ADOR LENGTH LD ID 
DPPSAMPl SD 0001 000000 0000C9 



PAGE 1 
ASM H V 04 09-15 U/04/75 



O 
(0 
(0 
O 

n 
o 

0) 

a 

o 

rt> 
n 

f+ 

o 

3 



LOC ORJFCT COOP 



SAMPLE PROGRAM PATCH ENTRY ROUTINE 



AOORl A00R2 STMT SOURCE STATEMENT 



ASM H V 04 09.15 11/04/75 



19 ^^^^^ittt* **************** *************************** ********* 00002000 

19 • MODULE NAME = DPPSAMPl ♦ 00002100 

20 ♦ DESCRIPTIVE NAME = SAMPLE PROGRAM PATCH ENTRY ROUTINE * 00002200 

21 * FUNCTION = DPPSAMPl FUNCTION IS TO BE PATCHED BY THE SPECIAL REAL ♦ 00003000 

22 * TIME OPERATING SYSTEM SAMPLE PfiOGR AMI OPPZSAMP ) * 00003100 

23 ♦ NOTES = THE PROGRAM IS ENTERED FOUR TIMES. ONE TIME BY A PATCH MACRO* 00003200 

24 • ISSUED BY DPPZSAMP AND THREE 1 SECOND CYCLIC PATCHES ISSUED BY • 00004000 

25 * A PTIME MACRO IN DPPZSAMP, * 00004100 

26 * DEPENDENCIES = NONE ♦ 00004200 

27 * RESTRICTIONS = NONE * 00005000 

28 * REGISTER CONVENTIONS = ALL REGS ARE ASSIGNED AS iR WHERE REGS 0-15 • 00005100 

29 ♦ ARE $0-$15 * 00005200 

30 ♦ MODULE TYPE = SAMPLE PROGRAM ♦ 00006000 

31 * PROCESSOR = ASSEMBLER F * 00006100 

32 ♦ MODULE SIZE = 208 DECIMAL BYTES * 00006200 

33 * ATTRIBUTES = REENTRANT * 00007000 

34 ♦ ENTRY POINT = DPPSAMPl * 00007100 

35 • INPUT = NONE * 00007200 

36 * OUTPUT = SPECIAL REAL TIME OPERATING SYSTEM MESSAGE 66 * 00008000 

37 ♦ RETURN = NORMAL OS/VS RETURN VIA BR 14. NO RETURN COOES ♦ 00008100 

38 * EXTERNAL REFERENCES = NONE * 00009000 

39 ♦ MACROS » BEGIN EXIT MESSAGE ♦ OOOIOOOO 

40 *********************************************************************** 0001 1000 



42 00013000 

43 ♦*» THE BEGIN MACRO WILL ESTABLISH A BASE REGISTER FOR DPPSAMPl 00014000 

44 *** 00015000 

45 BEGIN DPPSAMPl, BASE={12> ,SAVEA=IGETHAIN, WORK), LV=72 00016000 
000000 46tOPPSAMPl CSECT . 'MAIN* CONTROL SECTION Ol-BEGIN 



00000 
00001 
00002 
00003 
00004 



48+* 
49+ to 
50+ $1 
51+$2 
52+t3 
53* »4 



GOES THRU REGISTER EQUATE ONLY ONCE 



EOU 
ECU 
EQU 
EQU 
EQU 



0 ? 

1 ? 

2 ? 

3 7 

4 ? 



02-EQUAT 
02-EQUAT 
02-EQUAT 
02-EOUAT 
02-EQUAT 



> 





DPPSAMPl ~ 


SAMPtE 


PROGRAM 


PATCH ENTRY ROUTINE 






PAGE 3 


LOC 


OBJECT CODE 


ADORl 


A0DR2 


STMT SOURCE 


STATEMENT 


ASM H V 04 09. 15 


11/04/75 










00005 


54t$5 


EQU 


5 ? 


** 


02-EQUAT 










00006 


55*$6 


EOU 


6 ? 


**IF THESE SUBSTITUTES ARE USED AS 


02-EQUAT 










00007 


56+ 1 7 


EQU 


7 ? 


♦♦REGISTER NUMBERS THE CROSS-REFERENCE 


02-EQUAT 










00008 


57*»8 


EOU 


8 ? 


♦♦TABLE WILL PROVIDE A LIST OF WHERE 


02-EQUAT 










00009 


58+$9 


EOU 


9 ? 


♦♦EACH REGISTER WAS USED 


02-EQUAT 










OOOOA 


59H10 


EQU 


10 ? 


♦ ♦ 


02-EQUAT 










OOOOB 


60'fSU 


EQU 


11 ? 


♦ ♦ 


02-EQUAT 










OOOOC 


61*$12 


EQU 


12 ? 


♦♦ 


02-EQUAT 










OOOOD 


62+$13 


EQU 


13 ? 


♦* 


02-EQUAT 










OOOOE 


63+J14 


EQU 


14 7 




02-EQUAT 










OOOOF 


64+ $15 


EOU 


15 ? 


♦ ♦ 


02-EQUAT 










00000 


654'FPRO 


EOU 


0 




02-EQUAT 










00002 


66<-FPR2 


EOU 


2 




02-EQUAT 










00004 


67+FPR4 


EQU 


4 




02— EQU AT 










0 0006 


68+FPR6 


EQU 


6 




02-EQUAT 


000000 










70 + 


OS 


00 . 


FOR BOUNDARY ALIGNMENT 


Ol-BEGIN 










00000 


71* 


USING 


*, 15 . 


TEMPORARY BASE DECLARATION 


01-BEGIN 


000000 


47F0 


FOOE 




OOOOB 


72 + 


B 


14(0, 15 » 


BRANCH AROUND ID 


02- SAVE 


00000 4 


08 








73+ 


DC 


AL1(8) 


LENGTH OF IDB^TIFIER 


02- SAVE 


000005 


C40707E2CID407FI 




74 + 


DC 


CL8«DPPSAMP1» 


IDENTIFIER 


02-SAV6 


000000 


00 


















00000 E 


90 EC 


oooc 




OOOOC 


75+ 


STM 


14,12,12< 13) 


SAVE REGISTERS 


02-SAVE 


000012 


5800 


F034 




00034 


76 + 


L 


O.TKGOOOIG 


LOAD SP AND LV PARAMETERS 


01-BEGIN 












77 + * 


GETMAIN R,LV={0) 






000016 


4510 


FOl A 




OOOIA 


78+ 


BAL 


l,*+4 


INDICATE GETMAIN 


02-GETMA 


oooou 


OA OA 








79 + 


SVC 


10 


ISSUE GETMAIN SVC 


02-GETMA 


0000 IC 


50D1 


0004 




OOOCv 


80+ 


ST 


13.4(1) . 


SAVE CALLER'S SAVE AREA POINTER 


OX-BEGIN 


000020 


5010 


0008 




00008 


81 + 


ST 


1.8(13) . 


FOR DOWNWARD SAVE AREA TRACE 


01-BEGIN 


000024 


1801 








82 + 


LR 


13,1 . 


ESTABLISH OWN SAVE AREA POINTER 


Ol-BEGIN 


000026 


5810 


0004 




00004 


83+ 


L 


1,4(13) . 


RESTORE 15.0,1 


Ol-BEGIN 


00002A 


98EI 


lOOC 




OOOOC 


84 + 


LM 


14. 1, 121 1) 


RESTORE GET REGS 


01-BEGIN 


000000 










86+ WORK 


□SECT 




BEGIN GETMAINED AREA 


Ol-BEGIN 


000000 










87 + 


OS 


90 . 


OWN SAVE AREA 


0 l-BEGIN 


00002E 










88+DPPSAMPl 


CSECT 






Ol-BEGIN 










00000 


89+ 


US I NG 


WORK, 13 




Ol-BEGIN 


00002E 


0700 








91 + 


CNOP 


0,4 




01-BEGIN 


000030 


45C0 


F03R 




00038 


92 + 


BAL 


12,*+8 


ESTABLISH INITIAL 'MAIN* CSECT BASE 


Ol-BEGIN 


000034 










93+TKGOOOlM 


OS 


OF . 


BASE REFERENCE 


Ol-BEGIN 


000034 


00000048 






94+TKGOOOlG 


DC 


AL1(0),AL3(72I . SUBPOOL, LENGTH 


Ol-BEGIN 












95 + 


DROP 


15 




Ol-BEGIN 










00034 


96 + 


USING 


TKG0001M,12 




Ol-BEGIN 


000038 


5821 


0000 




00000 


97 


L $2 


:.0(tl) 


ADDRESS OF XCVT 


00017000 












98 


MESSAGE 66,VAR=(MSG) 


,DCVTR=($2) ISSUE MESSAGE 


00018000 


0000 3r, 










99 + 


CNOP 


0,4 




Ol-MESSA 


00003C 


4510 


C018 




0004C 


100 + 


BAL 


l,MSG0005 




Ol-MESSA 


000040 


01 








101+ 


DC 


ALU 0+1 ) 


VARIABLE COUNT 


Ol-MESSA 


000041 


00 








102 + 


DC 


AL 1< 0) 


ROUTI NG CODE COUNT 


Ol-MESSA 


000042 


0000 








103 + 


DC 


AL2(0) 


MESSAGE NUMBER 


01-ME SSA 


000044 


00 








104 + 


DC 


X«00« 


ACTION CODE 


Ol-MESSA 


000045 


000000 






105 + 


DC 


AL3(0) 


USER RETURN AREA 


Ol-MESSA 


000048 


0 0000000 






106 + 


DC 


lAL4tO) 


MESSAGE VAR lABLE 


Ol-MESSA 



o 

O 

n 

H- 
'O 
r>> 

o 
» 

0* 
o 

*t3 
<t> 
fi 
0> 
r+ 
H- 
O 
BS 

c 





DPPSAMPl - 


SAMPLE 


PROGRAM 


PATCH ENTRY ROUTINE 
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LOC 


OBJECT CODE 


ADOR 1 


ADDR2 


STMT SOURCE STATEMENT ASM H V 04 09.15 


11/04/75 


00CC4C 








107*MSG0005 OS 


OF 


01-McSSA 


00004C 


4100 0042 




00042 


108 •»■ 


LA 


Of 66 LOAD MSG # INTO REGISTER 0 


01-MESSA 


000050 


4001 0002 




00002 


109* 


STH 


0f2<n MOVE MSG i TO PARAMETER LIST 


01-ME SSA 


00005^ 


1 6f F 






llO* 


SR 


15, 15 ZERO REG 15 FOR IC 


01-MESSA 


000056 


43F1 0001 




OOOOl 


111* 


IC 


15,1(11 « OF ROUTE COOES IN PARAMETER LIST 


Oi-MESSA 


00005 A 


89 PO 0001 




0000 1 


112* 


SIL 


15,1 LENGTH OF ROUTE CODE IH PARAM LIST 


01-MESSA 


00005E 


4100 C056 




0008 A 


113* 


LA 


0,MSG VARIABLE ADOR 


01-MESSA 


000062 


5001 F008 




00008 


114+ 


ST 


0,8(1,15) STORE INTO MESSAGE LIST 


01-MESSA 


000066 


58F2 0020 




00020 


115* 


L 


15,32(($2)) ADDRESS OF CVT 


02-OPPSU 


00006A 


58FF 0090 




00090 


11&* 


L 


15, 116*28( 15J MESSAGE SUPPORT ROUTINE 


02-DPPSU 


00006E 


05EF 






117* 


BALR 


14,15 CALL SUPPORT ROUTINE 


02-DPPSU 










118 






00020000 










119 


THE EXIT MACRO WILL RESTORE ALL REGISTERS AS THEY MERE MHEN *** 


00021000 










120 *** 


DPPSAMPl WAS ENTERED AND WILL RETURN BACK TO THE SYSTEM 


00022000 










121 ♦«* 






00023000 










122 


EXIT 




00023100 


000070 








123* 


OS 


OH 


Ol-EXIT 


000070 


1810 






124* 


LR 


1,13 . SUBPOOL ADDRESS 


01-EXIT 


000072 


58D0 0004 




00004 


125* 


L 


13,4(13) . GET CALLER'S SAVE AREA 


Ol-EXI T 


0000 76 


5800 COOO 




00034 


126* 


L 


0,TKG0001G . LOAD SP APtf) LV PARAMETERS 


Ol-EXIT 










127** 


FREEMAIN 


R,LV={0),A=( 1» 




00007A 


4111 0000 




00000 


128* 


LA 


1,0(1,0) CLEAR THE HIGH ORDER BYTE XM4571 


02-FREEM 


00007? 


OAOA 






129* 


SVC 


10 ISSUE FREEMAIN SVC P2504 


02-FREEM 


000080 


9 8EC DOOC 




OOOOC 


130* 


LM 


14,12,12(13) RESTORE TH€ REGISTERS 


OZ-RETUR 


000084 


92 FF DOOC 


OOOOC 




131* 


MVI 


12{13),X'FF' SET RETURN INDICATION 


02-RETUR 


000088 


07FE 






132* 


BR 


14 RETURN 


02-RETUR 


00008A 


E3C1E292406040C4 




133 MSG 


OC 


CL63«TASK - DPPSAMPl WAS ENTERED AT ENTRY POINT - DPP SAMX00024000 


000092 


07D7E2CID407F140 








PI' 


00025000 










134 


END 




00026000 



CROSS REFERENCE 



SYMBOL 


LEN 


VALUE 


OEFN 


REFERENCES 


SI 


00001 


00000001 


0050 


0097 




$2 


00001 


00000002 


0051 


0097 


0115 


DPPSAMPl 


OOOOl 


00000000 


0046 


0088 




MSG 


00063 


00008A 


0133 


0113 




MSG0005 


00004 


00004C 


0107 


0100 




TKGOOOIG 


OOOOl 


000034 


0094 


0076 


0126 


TKGOOOIM 


00004 


00003f» 


0093 


0096 




WORK 


OOOOl 


00000000 


0086 


0089 
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DIAGNOSTIC CROSS REFERENCE AND ASSEMBLER SUMMARY 



PAGE b 



ASH H V 0* 09.15 11/04/75 

NO STATEMENTS FLAGGED IN THIS ASSEMBLY 

OVERRIDING PARAMETERS- NOOECK .NOLQAD, XREF (SHORT I 
OPTIONS FOR THIS ASSEMBLY 

NOOECK, NOOBJECT, LIST, XREFtSHORTJ, NORENT, NOTEST, NOBATCH, ALIGN, ESO, RLO, L I NECOUNT 1 55 I , FLAGIO), SYSPARM() 
NO OVERRIDING DO NAMES 

40 CARDS FROM SYSIN 1508 CARDS FROM SYSLl B 

163 LINES OUTPUT 0 CARDS OUTPUT 



w 
ss 
a 

M 
X 



I 



4£PENDIX_B. LISTING AIDS 



Much of the source code for the Special Real Time Operating System is 
written in OS/VSl assembler language using structured programming 
techniques. The structured programming vehicles for the Special Real 
Time Operating System are a set of macro instructions know as HLAL. 
HLAL is not a part of the Special Real Time Operating System PRPQ , but 
is distributed with it as a necessary aid in assembling most of the 
modules of the Special Real Time Operating System. 



Most assembler language programs written in structured code are easier 
to read if the nesting level of the various statements is printed along 
with the listing Also, the various statements should be indented to 
show the nesting level in a graphic manner. Nesting level refers to 
a statement being in a basis IF/THEN/ELSE structure, or structures 
within that structure- 



Two listing aid programs are provided with the Special Real Time 
Operating System PRPQ to facilitate the showing of the nesting level 
of the Special Real Time Operating System source modules. One of these 
programs, PPLPTPCH, post- processes the lEBPTPCH listing of a module; 
the other, PPLUPDTE, post -processes the lEBDPDTE listing of a module. 
Each program shifts the print line of its input to produce a structured 
listing- It does not alter (shift) the columns in which the source 
is actually resident in the source partitioned data set. It will 
automatically shift each member whose first card image does not contain 
the operation code of MACRO. 



Example 1 depicts the JCL which could be used to run both the PPLPTPCH 
and PPLUPDTE utility programs. Example 2 shows sample output from both 
programs. Example 3 shows the output from lEBOPDTE and lEBPTPCH as it 
would appear if the post-processor were not used. lEBUPDTE and lEBPTPCH 
are described in the SPL: OS/VSl Otilities, GC35-0005. 



PPLUPDTE and PPLPTPCH are contained in data set A5799 AHE. OBJECT. 
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a 

cn 
o 

o 
d 

PD 
0 

o 

M 

r+ 
H« 
O 
0 

at 

p 

c: 
P> 



//JOB 1 




JOB 




//A EXEC 




PGM=1EBPTPCM 




//SYSPRINT 


DO 


DUMMY 




//SYSUTl 


DD 


DSN=SOURCEDS» OISP»SHR 




//SYSUT2 


DD 


UNIT»SYSDA» SPACEa(CYL.( 1) ) » DISP- 


(NEW(PASS) « 


// 




OCB«(RECFM«FBA» LRECL«121» BLKSIZE 


•3630) 


//SYSIN 


DD 


» 




PRINT 




TYPORG=PO» MAXNAM=10f MAXFLDS-10 




MEMBER 




NAME«MEM1 




RECORD 




FIELD«(80) 




//B EXEC 




pgm«pplptpch 




//SYSUTl 


DD 


0SN=*.A.SYSUT2»0ISP»(OLDtDELETE) 




//SYSUT2 


DD 


SYSOUT«A 




//STEPLIB 


DO 


DSN«A5 799AHEf OBJECT .DISP-ShR 




//C EXEC 




PGM»1EBUP0TE 




//SYSPRINT 


00 


UNIT=SYSDA»SPACE«(CYL»(1»1») ) «DISP 


«(NEWtPASS> 


// 




DCB=(RECFM»FBA»LRECL«121 » BLKSIZE* 


3630) 


//SYSUTl 


DD 


osn«sourceos» disp=smr 




//SYSUT2 


00 


DSN«S0URCEDSi DISP-OLD 




//SYSIN 


00 


« 




/ CHANGE 


LIST=ALL»NAME«MEM1 








ST $6»G0RP SAVE REG 




GORP 


OS 


F 




//D EXEC 




PGM»PPLUPOTE 




//SYSUTl 


DO 


DSN«*,C«SYSPRINT» D ISP« ( OLD .PASS ) 




//SYSUT2 


DD 


SYSOUT-A 




//STEPLIB 


DD 


DSN»A5799AHE«OBJECT» DISP'SHR 





EXAMPLE I 



MEMBER NAME MEMl 

» SAMPLE MODULE TO ILLUSTRATE INDENTION 
IF C»ONE»EQ»TWO»TMEN 

# INDENTED COMMENT CAUSED BY ABOVE 
UNTIL (6tLOCtNE*3)OR 

(F«($6) *EQtX) »00 
7.L0C 
ETC *»♦»* 



01 
01 
01 
02 
02 
01 
01 



UNTIL 
STH 
L 

ENDOO 
• NOTE 

ENDIF 

END 



INDENTION MOVES BACK 



01000000 
11000000 



PAGE 0001 

01000000 
02000000 
03000000 
04000000 
05000000 
06000000 
07000000 
08000000 
09000000 
10000000 
12000000 



EXAMPLE 2 



MEMBER NAME MEMl 

* SAMPLE MODULE TO ILLUSTRATE INDENTION 

IF C»ONE»EO»TWO»THEN 

♦ INDENTED COMMENT CAUSED BY ABOVE 
UNTIL (B»L0CtNE»3) tOR 

UNTIL (F»<$6) »EQ»X) tOO 
STH 7»L0C 
L ETC •♦*♦» 



ENDDO 
• NOTE 



INDENTION MOVES BACK 
ENDIF 

END 



PAGE 0001 

01000000 
02000000 
03000000 
04000000 
05000000 
06000000 
07000000 
08000000 
09000000 
10000000 
12000000 



W 

M 

X 



SYSIN NEW MASTER 

•/ CHANGE LIST=ALL»NAME=MEM1 
IEB826I MEMBER NAME FOUND IN CM DIRECTORY AS AN ALIAS- 
♦ SAMPLE MODULE TO ILLUSTRATE INDENTION 
ST S6»G0RP SAVE REG 

IF C»0NE»E0tTW0»THEN 

♦ INDENTED COMMENT CAUSED BY ABOVE 
UNTIL (B»L0C .NE»3 ) fOR 
(F.($6) .EQ»X) tDO 
7»L0C 
ETC »♦♦•* 



01 
01 
01 
02 
02 
01 
01 



UNTIL 
STH 
L 

ENDDO 
* NOTE 
ENDIF 
GORP 
END 
IEB816I 
IEB818I 
IEB819I 



INDENTION MOVES BACK 



DS 



MEMBER NAME (MEMl 

HIGHEST CONDITION CODE WAS 00000000 
END OF JOB lEBUPDTE, 



lEBUPDTE LOG PAGE 0001 



01000000 
01100000 
02000000 
03000000 
04000000 
05000000 
06000000 
07000000 

ceoooooo 

09000000 
10000000 
11000000 
12000000 



) FOUND IN NM DIRECTORY. TTR IS NOW ALTERED 



CO 

I 



EXAMPLE 3 



tIJ 
I 



O 
(D 
01 
O 
II 
H- 

rt 
H- 
O 

0) 

P< 

O 

(D 
M 
P> 
f+ 
H* 
O 
0 

3 
P> 
0 



SYSIN NEW MASTER 

./ CHANGE LIST=ALL»NAME=MEM1 
IEB826I MEMBER NAME FOUND IN OM DIRECTORY AS AN ALlAS- 
CHANGEO TO TRUE NAME IN NM DIRECTORY. 

♦ SAMPLE MODULE TO ILLUSTRATE INDENTION 

ST $6»G0RP SAVE REG 

IF CtONE»EQ.TWO»THEN 
» INDENTED COMMENT CAUSED BY ABOVE 
UNTIL (B»LOC»NE »3 ) ♦OR 

UNTIL {F»($6) »EO»X) jDO 
STH ?»LOC 
L ETC ♦***» 

ENDDO 

* NOTE INDENTION MOVES BAC< 

ENOIF 
GORP DS F 

END 

IEB816I MEMBER NAME (MEM! ) FOUND IN NM DIRECTORY. 

IEB818I HIGHEST CONDITION CODE WAS 00000000 
IEB819I END OF JOB lEBUPOTE. 



lEBUPDTE LOG PAGE 0001 



01000000 
01100000 
02000000 
03000000 
04000000 
05000000 
06000000 
07000000 
08000000 
09000000 
10000000 
11000000 
12000000 
TTR IS NOW ALTERED. 



i££EllBIX_C- MQDOil fiAfil - FOWCTI 0» CHQSS pEP EREN CE 



H pd uj^e Hape 

DOMICEXT SUBSTITOTE EXTERNAL FIRST LEVEL INTERROPT 

HANDLER 

DOHIRBT FAILOVER/HESTART BOOTSTRAP AND PROBE 

DOHIRCHM CONTINOOOS MONITOR 

DOHIRCPY COPY A F AILOVER/RESTART DATA SET 

DOHIHFLV LOAD 1 F/H SVC 

D0MIRFL2 LOAD 2 F/R SVC 

DOHIRINT F/R-EXTERNAL INTERROPT INIT. 

DOHIRNIP RE-NIP 

DOHIRPRB PROBE 

DOMIRHT FAILOVER/HESTART WRITE 

THE FOLLOWING 3 MODOLBS ARE NAHED AT 
SYSGEM TIHE ACCORDING TO NOHBERS SUPPLIED 

D0MISVC1 TYPE 1 SVC PREFIX HANDLER 

D0HISVC2 TYPE 2 SVC PREFIX HANDLER 

DOHISVCU TYPE U SVC PREFIX HANDLER 

DOMXLIST PREPARE lEHLIST INPOT 

DOnXSTGI STAGE 1 OF SYSGEN UTILITY 

DPPCALCF CALCULATE TIHE CORRECTION FACTOR 

DPPCPTin PTIME MONITOR ROUTINE 

DPPCTIME TIME UPDATE ROUTINE 

DPPCTinE2 ALTERNATE TIHE UPDATE ROUTINE 

DPPCTSVC PTIME TYPE 2 SVC 

DPPCUPCF UPDATE TIME CORRECTION FACTOR 

DPPDARAY GET/PUTARRAY PROCESSOR 

DPPDBLOK GET/PUT BLOCK SUBROUTINE 

DPPDBSIF DATA BASE SLAVE PARTITION INTERFACE 

DPPDFEEQ CYCLIC LOGGING ROUTINE 

DPPDGETL GETLOG ROUTINE 

DPPDITEH GET/PUTITEM PROCESSOR 

DPPDPUTL PUTLOG ROUTINE 

DPPDRIFE DOMHY INIT. TIME SETTER 

DPPDBIFT TIME DRIFT CORRECTION 

DPPDSUB2 SLAVE PARTITION INTERFACE ROUTINE 

DPPDUMPL DOMPLOG ROUTINE 

DPPDDPDL LOGGING REFRESH ROUTINE 

DPPDWFST DATA BASE OPEN/CLOSE FOE RESTART 

DPPFAONC FORTRAN SUBROUTINE FOR 

COPY/ADDR/BIT SET 

DPPFIXFR PAGE FIX/FREE HANDLER 

DPPIDBAS DATA BASE INITIALIZATION 

DBPIIRP SCHEDULE I RB FOR DPPDHRST 

DPPILOGH LOGGING INITIALIZATION 

DPPINIT SYSTEM INITIALIZATION 

DPPINIT1 INITIALIZATION SUBSYSTEM PATCHOR 

DPPILOGN LOGGING INITIALIZATION 

DPPIPFIX PAGE FIX ROUTINE 

DPPIPFRE PAGE FREE/UNFIX ROUTINE 

DPPISTAE JOB STEP TASK STAE ROUTINE 

DPPITIHI TIME INITIALIZATION 

DPPHIHIT MSG HANDLER INITIALIZATION 

DPPKMSG SYSTEM MESSAGE FORMATTER 

DPPSfiSG? SYSTEM MESSAGE ROUTING CODE CHANGE 

DPPHMSG1 SYSTEM MESSAGE OUTPUT ROUTINE 

DPPPiFM PL/I AND FORTRAN PARAMETER INTERFACE ROUTINE 
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DPPPIF 

DPPLIO 

DPPSASOC 

DPPSBF1 

DPPSBFST 

DPPSCHCK 

DPPSCHPR 

DPPSCL 1 

DPPSCLOP 

DPPSCHPR 

DPPSCFBK 

DPPSCT2T 

DPPSINIT 

DPPSLOCK 

DPPSHSGI 

DPPSMSGO 

DPPSNOTB 

DPPSNTPT 

DPPS0P1 

DPPSOPCL 

DPPSPNTP 

DPPSRCIO 

DPPSHDWT 

DPPSRSTR 

DPPSSHAR 

DPPSSHCH 

DPPSST1 

DPPSS WCH 

DPPSTBOS 

DPPSONLK 

DPPSONSH 

DPPSHRST 

DPPSXTCB 

DPPTCBGT 

DPPTCSVC 

DPPTDLMP 

DPPTDSVC 

DPPTETXR 

DPPTGWFW 

DPPTIilPS 

DPPTPnOM 

DPPTPSVC 

DPPTPWQE 

DPPTQIHP 

DPPTRSVC 

DPPTSMON 

DPPTSTAB 

DPPTHAIT 

DPPTWQDL 

DPPTWS7C 

DPPUBSG 

DPPXDBAS 

DPPXDBAT 

DPPXDBCP 

DPPXDBDA 

DPPXDBIN 
DPPXDBLG 



PL/I AND FORTRAN INTERFACE ROUTINE 

PL/I OPTIMIZIER INVOKATION ROUTINE 
DDS ASYNCHRONIS OPEN OR CLOSE 
BLDL FIND TYPE D FOR A DDS 
BLDL FIND TYPE D STOH FOR A DDS 
DDS CHECK WODaLE 

SET A PRIMARY DECB AND A BACKOP DECB 

CLOSE A DDS 

DDS CLEAN OP ROUTINE 

COMPARE FOR DDS 

CREATE A DDS BACKOP 

COPY TRACK TO TRACK 

INITIALIZE THE DDS SYSTEM 

LOCK A DDS 

DDS INPOT MESSAGE PROCESSOR 

DDS HESSSAGE OOTPOT PROCESSOR 

PERFORM NOTE ON A DDS 

BRANCH CODE FOR NOTE POINT 

OPEN A DDSDCB 

OPEN CLOSE HALF OF A DDS 

PERFORM POINT FIND TYPE C ON A DDS 

RECREATE I O FOR A DDS HALF 

READ WRITE MODULE FOR DDS 

DDS PAIL07ER/RESTART 

SHARE A DDS 

SEARCH A FIXED LENGTH TABLE FOR AN ENTRY MHO 
STOH FOR A DDS 

SWITCH PRIMARY TO BACKOP FOR A DDS 
TAKE A BACKOP OUT OF SERVICE 
UNLOCK A DDS 
UNSHARE A DDS 
DDS WRITE STATUS 

LOCATE ALLOCATE A DDSXTCBC FOR AN INPUT TASK 

CBGET TYPE 1 SVC ROOTINE 

CHAIN TYPE 1 SVC ROUTINE 

LOAD MODULE PURGE 

DPATCH SVC RTN 

END OF TASK EXIT 

GETWA/FRBEWA INTERFACE 

STAE INITIALIZATION 

PATCH MONITOR 

PATCH SVC RTN 

PURGEWQ ROUTINE 

QS IMP COMMAND PROCESSOR 

REPATCH SVC RTN 

SYSTEM MONITOR 

STAE DUMP/NODOMP ROUTINE 

PURGEWQ WAIT ROUTINE 

WQE DELETE RTN 

GETWA-FREEWA TYPE 1 SVC ROUTINE 

SYSTEM MESSAGE OFFLINE PROCESSOR 

DATA BASE FINAL PHASE PROCESSOR, FIRST LOAD 

DATA BASE FINAL PHASE PROCESSOR, SECOND LOAD 

DATA BASE BDAH DATA SET COMPRESS 

DATA BASE FINAL PHASE PROCESSOR SUPPORT ROUTINE 

TO WRITE DATA TO DATA BASE BDAH DATA SETS 

OFFLINE DATA BASE TABLE CONSTRUCT 

DATA BASE FINAL PHASE PROCESSOR 

SUPPORT ROUTINE TO CALCULATE 

LOGGING ARRAY BLOCK COUNT AND 

BLOCK SIZE 
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DPPXDBPT 

DPPXDBFL 

DDPPXDPB 

DPPXDRC 

DPPXDRCX 

DPPXIHPP 

DPPXIHPH 

DPPXKILL 

DPPXLOCK 

DPPXNRTI 

DPPXPCOH 

DPPXRDR 

DPPXRIHT 

DPPXRPRT 

DPPXS2SC 

DPPXSVCP 
DPPXOTIL 
IEAXYZ5 



DATA BASE PRIHT OTILITT 

DEFIHE LOCK ROUTINE 

DATA RECORDING AND PLAYBACK 

DATA RECORDING COLLECTION ROUTINE 

DOHHT DATA RECORDING COLLECTION 

INPOT MESSAGE PROCESSOR 

INPUT HESS AGE PROCESSOR iTOR ROUTINE 

ORDERLY TERMINATION ROUTINE 

LOCK ROUTINE 

DATA PLAYBACK OFFLINE ENTRY ROUTINE 

PLAYBACK REQUEST INTERPRETER 

DATA PLAYBACK PRINT ROUTINE 

DATA RECORDING INITIALIZATION 

REPORT DATA OUTPUT PROCESSOR 

LOCATE INSERT CARDS IN 0S/VS1 STAGE II 

SYSGEN DECK 

SETPSH TYPE 1 SVC 

OFFLINE UTILITY CONTROL PROGRAM 
ALTERNATE NAME FOR DOHICEXT 
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A£2M£lX^JDi S££CIAL BEAL IMl OPERAyiNG SIST^ PROGRMS/lfilCROS 



Below are programs/macros that comprise the Special Real Time Operating 
System program package. Macros are noted with asterisks. 



SasiS Sourge P£ograms/ilacros 



ARRAY 


* 


DDSDCB 




DPPTNOTE 


♦ 


ARRAYDEF 




DDSFIND 


* 


DPPTPSVC 




BEGIN 


* 


DDSOPEN 


* 


DPPTRSVC 




BGKSEG 


* 


DDSSTOH 


* 


DPPTSETB 




BIT 


* 


DECDEC 


* 


DPPTWQDL 




BLOCK 


♦ 


DECHEX 


* 


DPPXBLKS 


* 


BLOCKDEF 




DEFLOCK 


* 


DPPXBRT 


* 


BYTE 




DEFMSG 


* 


DPTDEBUG 




CASE 


* 


DO 




DPTDSVC1 




CBFREE 


♦ 


DOMBOOTH 


♦ 


DPTECBCC 




CBGET 


* 


DOHICEXT 


* 


DPTPSVC1 




CHAIN 


* 


DOMIEBT 


* 


DPTPSVC2 




CINFD 


* 


DOMIRCME 




DPTPSVC3 




CLOSESEG 


* 


DOMIRCMN 




DPTPSVC4 




CONFIGH 


* 


DOMIRPRB 


* 


DPTPSVC5 




C0NF1 


* 


DOMIRSIO 




DRECBLKS 


* 


DATASET 


* 


D0MISVC1 


* 


DOMPLOG 


♦ 


DBALTPRI 


* 


D0MISVC2 


* 


DOPDISK 




DBALTSEC 


* 


DOMISVCU 


* 


ELSE 


♦ 


DBARRAYD 


* 


DOMSVCN 




ENDDO 


* 


DBASE 




DPACHDEF 




ENDIF 


* 


DBBLOCKD 


♦ 


DPATCH 




ENDLOOP 




DBDACNTL 


* 


DPINIT1 




ENDSEG 


* 


DBDADD 


* 


DPINIT2 




ENDSRCH 


* 


DBDEF 


* 


DPINIT3 




ENTER 




DBDEFD 


* 


DP IN IT a 




RQOATE 


* 


DBDIRB 


* 


DPIKIT5 




ERRENTER 


* 


DBDIRR 


* 


DPLOGDEF 




ER RETURN 


* 


DBDMPHDR 




DPPERM AC 


* 


EFREXIT 




DBEND 


* 


DPPFIX 




ERRMSG 




DBGBLPAK 




DPPFIX2 


* 


EXIT 


* 


BGNWHILE 




DPPFREE 


* 


EXITIF 


* 


DBITEMD 


* 


DPPPINIT 


* 


FAILRST 


♦ 


DBLOGCB 


* 


DPPLEVEL 




FORSUB 


* 


DBLOGHDR 




DPPSOB 


* 


FREEWA 


* 


DBPBT 




DPPSVC 


* 


GENCOMCK 




D6W AREA 




DPPSVC9 




GENEMS 


♦ 


DDSBLDL 


* 


DPPTDSVC 




GENINIT 


* 


DDSCLOSE 




DPPTETXM 




GEN30 


♦ 


GEN370 


* 


OR SELSE 


* 






GEN370CK 




PARM 


* 






GEN3702 


* 


PARMDEF 








GEN73A 




PATCH 


* 






GEN73LE 


* 


PATCHDEF 








GEN73N6 




PLISUB 


* 






GEN73Z 


* 


PNCHASM 








GET ARRAY 


* 


PNCHDD 


♦ 






GET BLOCK 


* 


PNCHLE 








GETITEM 


♦ 


PRN 








GETLOG 




PTIME 


* 






GETWA 


* 


PTIMEDEF 








GLOBAL 




PTIMEL 








GLOBALI 




PTIMRDEF 
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GPETaPN 


* 


PTLOGDEF 




GTLOGDEF 




PUSGEffQ 




HEADC 




PUTARRAT 


* 


HEXDEC 


* 


PUTBLOCK 


* 


IF 




POTITEM 


* 


IMP 


* 


PUTLOG 


* 


IMPBLKS 




RECORD 


* 


ITEM 




RECRDDEF 




ITEMDEF 




REPATCH 




LENGTH 


♦ 


REPCHDEF 




LOCK 


* 


SE TPSH 


♦ 


LOCKCBLK 




STRTSRCH 


♦ 


LOG 




SOPL 




L0G2 


* 


SYSLEVEL 




MAINBLOK 


* 


TIMED 


♦ 


MATH 


* 


TMBIT 


* 


MESAGDEF 




UNTIL 




MESSAGE 


* 


VS 


* 


MSGBLKS 


* 


WAITDEP 




MSGDEF 


* 


WHILE 




MSGEND 


* 


WTFAILDS 




MSGPC 


* 


XI BIT 




NIBIT 


* 






OIBIT 


♦ 






OPENSEG 









D-2 



Description and Operation Manual 



Ba:; i.c Qble£i Prograas 



DOHIFCPY 


DPP3 AHP1 


DPPSONLK 


Don IRFL V 


DPPSASOC 


DPPSDNSH 


D0flIRFL2 


DPPSBFST 


DPPSWRST 


UUninlNT 


DPPSBF 1 


DPPSXTCB 


n u T n M T n 

DOnlRNI P 


DPPSCHCK 


DPPTCBGT 


DOHIRHT 


DPPSCHK2 


DPPTCS VC 


DOHXLIST 


DPPSCHK3 


DPPTDLHP 


DONXSTG 1 


DPPSCHK4 


DPPTETXE 


DPPCALCP 


DPPSCHPR 


DPPTGHFH 


DPPCPTIH 


DPPSCLOP 


DPPTIHPS 


DPPCPTI ME 


DPPSCL 1 


DPPTPMOW 


DPPCTIH 2 


DPPSCHPR 


DPPTPHQE 


DPPCTSVC 


DPPSCP2B 


DPPTQIBP 


DFr CUPCF 


DPPSCRBK 


DPPTRGWA 


U F PD AF A I 


DPPSCT2T 


DPPTSHON 


DP r DdLOK 


DPPSDDSX 


DPPTSTAE 


DPPDBSI F 


DPPSDSCB 


DPPTHAIT 


DPPDFREQ 


DPPSINIT 


DPPTHSVC 


DPPDGETL 


DPPSIHI2 


DPPOHSG 


DPPDITEH 


DPPSIMI3 


DPPXDBAS 


DPPDPOTL 


DPPSIN 14 


DPPXDBAT 


DPP DR IFE 


DPPSINI5 


DPPXDBCP 


DPPDRIFT 


DPPSINI6 


DPPXDBDA 


DPPDS 0B2 


DPPSLOCK 


DPPXDBLG 


DPPDOHPL 


DPPSHSGI 


DPPXDBLG 


DPPDOPDL 


DPPSMSGO 


DPPXDBPT 


DPPDHRST 


DP PS MOTE 


DPPXDEFL 


DPPFAOHC 


DPPSMTPT 


DPPXDPB 


DPPFIXFR 


DPPSOPCL 


DPPXDRC 


DPPIDBAS 


DPPS0P1 


DPPXDRCX 


DPPIIRB 


DPPS0P2 


DPPXIHPP 


DPPILOGM 


DPPSPHTF 


DPPXIHPV 


DPPXNITO 


DP PS RC 10 


DPPXKILL 


DPPINIT 1 


DPPSRD WT 


DPPXLOCK 


DPPIPFI X 


DPPSRDH2 


DPPXMRTI 


DPPIPFRE 


DPPSRLSE 


DPPXPCOR 


DPPISTAE 


DPPSRSR? 


DPPXRDR 


DPPITini 


DPPSRSTH 


DPPXRIMT 


DPPHINIT 


DPPSSHAR 


DPPXRPHT 


DPPHBSG 


DPPSSRCH 


DPPXSVCP 


DPPMMSG7 


DPPSST 1 


DPPXS2SC 


DPPHMSG1 


DPPSSSCH 


DPPIOTIL 


DPPPARM 


DPPSTBOS 


DPPZSAMP 


DPPPIF 


DPPSTKCK 





DPPPLIO 
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ODSHSG 

ETXRHSG 

PAILRBT 

FAILBPBB 

P&ILRSTH 

IMITHDCS 

SRTOSMSG 
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BIGHOVE 


* 


DPINIT08 




DPPPARH 




CVDEBC 


* 


DPINIT09 




DPPPIF 




DBARBLDL 




DPPINITOA 




DPPPLIO 




DBIITEHR 




DPIHIT11 




DPPSABPI 




DBREFRSH 




DPINIT12 




DPPSASOC 




DBSORT 


* 


DPINIT13 




DPPSBFST 




DDSDSECT 




DPINIT 14 




DPPSBF1 




DDSNTPT 




DPITIHI1 




DPPSCHCK 




DDSSOLU 




DPPCALCF 




DPPSCHK2 




DDSTSSC 




DPPCPTIH 




DPPSCHK 




DOMIPCPY 




DPPCTIHE 




DPPSCHKU 




DOMIRFLV 




DPPCTIM2 




DP PSCHPR 




D0BIRFL2 




DP PCTS VC 




DPPSCL UP 




DOMIRINT 




DPPCUPCF 




DPPSCL 1 




DOMIRNIP 




DPPDARAY 




DP PSCHPR 




DOHIRWT 




DPPDASOB 




DPPSCP2B 




DOMXLIST 




DPPDBLOK 




DPPSCRBK 




D0MXSTG1 




DPPDBSIF 




DPPSCT2T 




DPCALCF1 




DPPDFREQ 




DPPSDDSX 




DPCTIHE1 




DPPDGETL 




DPPSDSCB 




DPCTIBE2 




DPPDITEH 




DPPSINIT 




DPCTIM21 




DPPDPUTL 




DPPSINI2 




DPCTIM22 




DPPDRIFE 




DPPSINI3 




DPCTSVC1 




DPPDRIFT 




DPPSINIU 




DPCTSVC2 




DPPDSTRT 




DPPSINI5 




DPCTSVC3 




DPPDS0B2 




DPPSINI6 




DPCTSVC4 




DPPDOMPL 




DPPSLOCK 




DPCUPCF1 




DPPDUHPL 




DPPSHSGI 




DPC0PCF2 




DPPDHRST 




DPPSHSGO 




DPCUPCF3 




DPPF AONC 




DPPSNOTE 




DPCOPCF'* 




DPPPIXPR 




DPPSNTPT 




DPIDBAS1 




DPPIDBAS 




DPPSOPCL 




DPIDBAS2 




DPPIIRB 




DPPSOP 1 




DPIDBAS3 




DPPILOGN 




DPPS0P2 




DPIDBAS5 




DPPINITO 




DPPSPNTF 




DPIDBAS6 




DPPINIT1 




DPPSRCIO 




DPINIT01 




DPPIPFIX 




DPPSRDHT 




DPINIT02 




DPPIPFRE 




DPPSRDW2 




DPINIT03 




DPPISTAE 




DPPSRLSE 




DPIHIT04 




DPPITIHI 




DPPSRSRV 




DPINIT05 




DPPniSIT 




DPPSRSTR 




DPINIT06 




DPPMHSG 




DPPSSHAR 




DPINIT07 




DPPBMSG? 




DPPSSRCH 




DPPSS WCH 




DPPMMSG1 




DPPSST1 




DPPSTBOS 




DPPXS7CP 




PSECTEND 


* 


DPPSTKCK 




DPPXS2SC 




PWQE 




DPPSONLK 




DPPXOTIL 




QHBK 




DPPSONSH 




DPP2SABP 




QPBK 




DPPSMBST 




DPTCS7C1 




RCALL 




DPPSXTCB 




DPTDLHP1 




RCSHEAD 


* 


DPPTCBGT 




DPTDLBP2 




RLHHEAD 




DPPTCSVC 




DPTDLMP3 




SETO 




DPPTDLMP 




DPTDLMP4 




SETPB 


* 


DPPTETXR 




DPTDLHP5 




ST AEBLK 


* 


DPPTGWFW 




DPTPH0H1 




ST AEXBK 


* 


DPPTIMPS 




DPTPH0N2 








DPPTPMON 




DPTPH0N3 








D?PTP«QE 




DPTPHONU 








DPPTQiaP 




DPTPM0N5 








DPPTRGHA 




DPTSH0M1 








DPPTSfiOK 




DPTSSVCI 








DPPTSTAS 




DPTWS?C2 








DPPTW AIT 




DPTSSVC3 
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DPPTWSVC 


DPXDBIN1 




DPPDHSG 


DPXDBIN2 




DPPUHSG1 


DPXDBIN3 




DPP0flSG2 


DPXDBIN4 




DPPXDB&S 


DPXDBIN5 




DPPXDBAT 


DPZDBIN6 




DPPXDBCP 


FINDPARH 


* 


DPPXDBDA 


GHSG 




DPPXDBIN 


HEXBBC 




DPPXDBLG 


INITCB 


* 


DPPXDBPT 


IPROB 


* 


DPPXDEPL 


LTYP 


* 


DPPXDPB 


BARKHASK 


* 


DPPXDRC 


HASKDATA 


* 


DPPXDFCX 


MXSTG101 




DPPXIHPP 


BISTG102 




DPPXIMPW 


SXSTG103 




DPPXKILL 


nXSTG104 




DPPXLOCK 


MX STG105 




DPPINRTI 


PPLPTPCH 




DPPXPCON 


PPLSCAM 




DPP.TRDR 


PPLSCAM2 




DPPXRINT 


PPLOPDTE 




DPP HPHT 


PSECT 


* 



D-6 



Description and Operation Manual 



APPENDIX G 



GLOSSARY 



This manual introduces many nei* terms and acronyms not commonly used 
in data processing. This glossary defines those terms unique to or 
having a special meaning in this program and this manual. Accordingly, 
terms which are included in the IBM Data Processing Glossary (GC2 0-16 99) 
are not included here- 

Term Definition 

Array An arrangement of data items in one or more dimensions. 

Block One or more data items. One or more blocks of equal 

dimensions make up an array. 

Blocked An array consisting of one or several blocks, A blocked 

array may be either VS or DA resident and may be accessed 
through GETBLOCK and PDTBLOCK. 

Backup The secondary copy of a duplicate data set pair. 

Continuous A program that resides and executes in the monitor online 

CPU and monitors specified storage locations to ensure 
that the online system is functioning. 

DA Resident A term used to group arrays by their residence during 

online operation. DA resident specifies that the array 
resides on direct access storage during online operation. 

Data Base The collection of data arrays and control information 

consisting of one partitioned data set, and one or more 
direct data sets. During real-time processing, part of 
data base will be loaded into virtual storage. 

Dependent Task A task created by the Special Real Time Operating system 
without a task name, A dependent task executes only 
once. 



Duplicate 
Data Set 



Failover 



A feature of the Special Real Time Operating System that 
allows for duplicate copies of critical data sets to be 
maintained by executing duplicate I/O accesses. 

The procedure by which the backup CPU is made to become 
the primary CPU, 



Independent 
Task 



Item 



Lock 



Log (Logging) 



A task created by the Special Real Time Operating System 
with a task name. An independent task remains in 
existence after it has executed and is capable of 
executing program cyclicly. 

One member of a group, one or more items make up an 
array, 

A method of controlling a resource so that only one 
program may use the resource at a time. 

The process of copying a VS resident array to a log 
dataset (DA resident) . 
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Log Array A DA x will contain the copy or copies 

of the VS L<i^ .e array. 

Log Header The control informatiok .^osociated with the VS resident 

loggable array. 

Master The controlling partition in a two partition operation. 

Normal Start The process by which the Special Real Time Operating 
System is initializing from the control statements in 
the input stream using the initial diata loggable arrays- 
Offline That processing which is executed not under control of 

the Special Real Time Operating Systen^ i.e., processing 
in another CPO or in a non-real time partition. 

Online That processing which is executed under control of the 

Special Real Time Operating System, i.e., as a subtask 
of the Special Real Time job step task itself. 

Playback The process by which the data previously collected by 

the data record routine is retrieved and deformatted. 

Primary The main CPO in a multiple CPU environment; i.e., the 

CPU which is currently controlling the functions for 
the real-time environment. Also the main copy of a 
duplicate data set group. 

PROBE That program that runs in the backup computer and tests 

the continuous monitor in the online CPU. If the value 
on the direct control static data lines fails to change 
during twice of the update interval, the PROBE recommends 
a failure. 

Record The processing of collecting specified data and saving 

it in a formatted mode for later retrieval by the 
playback function. 

Refresh The process by which the Special Real Time Operating 

System is initialized using the most recent copies of 
loggable arrays. A refresh start may be from the input 
stream or from a failure data set. 

Resource Table An 8-byte area provided by the Special Real Time 
Operating System for each real-time task. 

Restart The procedure by which a real-time CPO is reinitialized 

to the point at which the failover restart data set was 
wr itten. 

SLAVE That partition in a two-partition real-time operating 

system which contains only some of the Special Real Time 
Operating System services. The services not contained 
in the SLAVE partition are provided by the MASTER 
partition. 

Status Panel A user fabricated hardware panel used to indicate which 
CPU is primary and which is backup in a real-time 
environment and also to indicate when and how a failover 
is to occur. 

Time Drift The variation of the System/370 Time of Day Clock from 

the absolute time. 
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Unblock The freeing of a resource that had previously been 

reserved by the LOCK function. 

Unblocked The freeing of a resource that had previously been 

reserved by the LOCK function. 

?S Resident An array that resides in virtual storage. 
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READER'S COMMENT FORM 



IBM Svstem/370 



SH20-1 773-1 



Special Real Time Operating System 

Programming RPQ Z06751 

Description and Operation Manual 

Please comment on the usefulness and readability of this publication, suggest additions and 
deletions, and list specific errors and omissions (give page numbers). All comments and sugges- 
tions become the property of IBM. If you wish a reply, be sure to include your name and address. 



COMMENTS 



Fold 



Fold 



Fold 



Fold 



• Hunk vou tor your njnporaiion. No postai;«: necessary if mailed in the U.S.A. 
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Your comments, please . . . 

This manual is part of a library that serves as a reference source for systems analysts, 
programmers, and operators of IBM systems Your comments on the other side of this 
form will be carefully reviewed by the persons responsible for writing and publishing 
this material. All comments and suggestions become the property of IBM. 
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